site management

[emiliom]

Accumulating some links / resources / comments to help me with the current state of the web site:

See also this old (but still relevant) issue, #14

Ask Filipe for help?!

From BioData-Training-Workshop

• https://github.com/ioos/BioData-Training-Workshop/tree/gh-pages
• Miscellaneous template instructions ioos/BioData-Training-Workshop#1
• https://ioos.github.io/website-deployment-jekyll.html

From GHW vector tutorial (software carpentry template)

• https://github.com/geohackweek/vector/

[emiliom]

From exchange with Amanda:

EM: https://github.com/oceanhackweek/oceanhackweek.github.io is obviously the main site, but it looks like https://github.com/oceanhackweek/jekyll-spectral-theme also has elements that need to be modified? There's no CI in place to build the Jekyll static pages, right?

Ditto for the wiki site. I see https://github.com/oceanhackweek/wiki and https://github.com/oceanhackweek/jekyll-hackweek-wiki, though the latter didn't get anything but one trivial update in 2019, so I assume it's not something we used last year?

AT: yes it’s very convoluted. Don had set it up before. You will need to first update the submodule, which is where all the posts/info are oceanhackweek/jekyll-spectral-theme, then commit and push and then commit and push oceanhackweek/oceanhackweek.github.io

It might be easier for me to do the website updates if you want, otherwise we might need to overhaul the whole thing. It’s extremely convoluted.

[leewujung]

I highly recommend an overhaul to the website. It is too difficult to maintain at the moment and not keeping up with jekyll theme updates either.

[emiliom]

Thanks for chiming in @leewujung. Anyone in mind who could do this quickly? @amanda-tan? I was planning to contact Filipe with help to incrementally fix the site and guide us, but unless we get lucky and he has time right now, it's a wild card.

Are the other HackWeek sites that use the same theme (GHW, WHW) also in the same convoluted state??

[emiliom]

Looking at the GHW and WHW repos, I see that -- unlike OHW -- they don't rely on a theme submodule. Looks like what we need is to move from using a submodule to a baked-in theme

[emiliom]

@ocefpaf has volunteered to help us. Thanks!!!

[ocefpaf]

There's no CI in place to build the Jekyll static pages, right?

@emiliom that is correct. GH builds jekyll site "for free."

Looking at the GHW and WHW repos, I see that -- unlike OHW -- they don't rely on a theme submodule. Looks like what we need is to move from using a submodule to a baked-in theme

I agree. The question is:

• do you want to start fresh based on GHW and WHW or you want to pull the submodules, update, and "bake" the theme in the site?

[emiliom]

@emiliom that is correct. GH builds jekyll site "for free."

Thanks for confirming. I realized this later. But I was also expecting to see a gh-pages branch; I forgot a gh-pages branch is no longer required.

The question is: do you want to start fresh based on GHW and WHW or you want to pull the submodules, update, and "bake" the theme in the site?

What do you recommend? Priorities that come to mind are ease of transition, maintainability, and minimizing potential problems down the road. Your PR #44 would bake the theme in, which seems fine to me even if we change course later.

[emiliom]

Alright, we're in business! I made a very small change (just to the config file), to update the year and date of the event, and the site updated as expected.

Thanks again, @ocefpaf!!! It looks like we're good to go for now, for updating content in a reasonably efficient way. But if you have any suggestions for further cleanups or overhauls that would make things better, I'm all ears! Or just submit a PR 😃

I'm leaving this issue open for now, to add documentation about updating the content, and in case new issues pop up.

[emiliom]

Jekyll Spectral theme, http://jekyllthemes.org/themes/spectral/

Location of main content documents

• _config.yml: core site configuration, including some banner/header/footer text and urls
• jekyll-spectral-theme/_includes: front page content, broken up into sections
  • Individual sections and their order seem to be controlled by jekyll-spectral-theme/_layouts/default.html
  • Each section specifies a template for its layout, where the templates available are found in jekyll-spectral-theme/_layouts
  • Section two ("Information for Applicants") is a special beast. While jekyll-spectral-theme/_includes/section-two.html orchestrates it, the directives there point to content to be grabbed from tags title and description in _pages/01-applicants.md
• _pages: content for extra pages, including all the pages accessible via the menu on the upper right
  • The destination page file name is not the file name on the repository; instead, it's found in the permalink tag within the file. For example, for _pages/01-applicants.md, the destination file name is applicant-info.html

There might be more; these are the ones I'm certain about.

Prior OHW content - 2018

• https://oceanhackweek.github.io/ohw2018/ (https://github.com/oceanhackweek/ohw2018)
• https://github.com/oceanhackweek/oceanhackweek.github.io/blob/master/_pages/z-projects_2018.md
• https://github.com/oceanhackweek/oceanhackweek.github.io/blob/master/_pages/z-schedule_2018.md

[emiliom]

Testing locally with Jekyll

Instructions from @ocefpaf:

One can install jekyll locally with:

conda create --name JEKYLL rb-bundler compilers
conda activate JEKYLL
bundle install

and then type:

bundle exec jekyll serve

to build and serve the site at http://127.0.0.1:4000/.

[emiliom]

I've created a document with instruction for editing the content of the web site (_InstructionSiteUpdates.md). It's largely taken from my last two comments on this issue, with small tweaks for readability.

[emiliom]

@ocefpaf is there an easy way to have a dev version of the repo that gets auto-rendered just like the master branch? By easy I mean something like a dedicated branch. That'd be very convenient for proposing a change and have others review it w/o asking everyone to clone it and run jekyll.

[ocefpaf]

@ocefpaf is there an easy way to have a dev version of the repo that gets auto-rendered just like the master branch? By easy I mean something like a dedicated branch. That'd be very convenient for proposing a change and have others review it w/o asking everyone to clone it and run jekyll.

One of those GH actions was supposed to do exactly that. If I cannot make it work I'll create a "dev" version of the page that we can publish.

[emiliom]

I thought I remembered you referring to that. But yes, I know GH actions are not an option right now. Thanks.

[ocefpaf]

I thought I remembered you referring to that. But yes, I know GH actions are not an option right now. Thanks.

The alternative is as laborious as trying to fix the GH action, so I'm investing the my time on the latter first. If I failed I'll get back to the former.