Editor Guide
This is a partial guide to editing this site. Documentation for the custom Hugo shortcodes used and advice for adding images is in the Images & Video page.
See the official Hugo Documentation if needed.
This ‘Editor Guide is linked in the site footer when Hugo is running in server mode for editing on your own computer, it will not be linked on the production site. The Editor Guide pages are set to ‘draft: false’ in front matter and will still be available on the production site at jalview.org/editor-guide.
Initial Setup
Is documented in In Hugo Setup
Running Hugo
Running hugo server will generate the site and set up a local server at http://localhost:1313 but adding some extra command line flags can be helpful:
hugo server --navigateToChanged --gc
--navigateToChanged will causes the browser to display the page being edited. --gc tells Hugo to clean up unused resources.
If you are editing the templates or stylesheets you may also need --disableFastRender to have any changes rendered (this increases build time however):
hugo server --disableFastRender --navigateToChanged --gc
Editing Content
The vast majority of content is in Markdown format with additional Hugo shortcodes. See Hugo Documentation for details. Some custom Jalview theme shortcodes are described in Images & Video.
The ‘front matter’ of pages is in YAML format.
Most popular code editors have plugins for both Markdown and Hugo which can be helpful, particularly when it comes to not automatically reformatting and breaking the YAML front matter!
Most of the content uses Hugo Page bundles that bundle together all resources (markdown file ‘index.md’, images, files for download etc) for a particular page inside a directory.
For the most part the URL of a page follows the filesystem structure. So for example:
document: content/help/getting-started/index.md
url: jalview.org/help/getting-started/
There are some exceptions to this, in particular there is a lot of old content that uses a url parameter in the front matter to specify it’s location in the published site (see archived news posts for example).
New pages are created using the hugo new command run from the top level directory, there is no need to specify the ‘content/’ directory when using hugo new.
There are specific Hugo ‘Archetype’ templates for News, FAQ and Release pages (you can edit the templates in the top level archetypes directory), adding new pages is detailed below.
Adding a new ‘News’ post
Use the hugo new command and specify filesystem location and title in the form of a url.
hugo new news/2021/Jalview-website-revamped
Then edit the front matter of the new document to add a proper title, suitable news cateory etc - notes are provided inline. Don’t forget to change the draft parameter to false when you’re ready to publish the article.
Adding a new Jalview ‘Release’
Use the hugo new command and specify location and title in the form of a url.
hugo new --kind release development/archive/Jalview-21116
Then edit the front matter add a proper title, change dates etc - notes are provided inline. Don’t forget to change the draft parameter to false when you’re ready to publish the release announcement.
(Note that unlike News articles we need to specify the archetype to use with --kind because the releases are in ‘archive’ and Hugo cannot automatically figure out which archetype to use.)
Adding a new FAQ
Again, hugo new, then edit the new page:
hugo new --kind faq help/faq/title-of-a-new-faq
The FAQs are sorted in order of weight on the FAQ page. To help you decide which weight to apply to a particular FAQ item the weight is rendered in orange next to the FAQ when in server mode (in the list at the top). FAQs will list alphabetically next to others of the same weight.
Adding a new Page
This is simpler since it uses the default template e.g.
hugo new schools/coronavirus-workbook
But there is some added complexity where you need to have the page appear in one of the site menus. Please look at existing pages in the same location to see how to add menu entries to the front matter and whether you need to specify a ’layout’ template there.
Note that pages starting with an underscore _index.md are section index pages and will use a section template for rendering rather than the single template.
Code blocks and automated syntax highlighting
Hugo has built in support for syntax highlighting of code blocks with Chroma - this has been extensively used for FAQ items and here in this page. These use simple Github style code fences with backticks. And use single backticks for inline code. Alternatively you can use Hugo’s highlight shortcode.
Chroma uses a theme system. It’s been set up with the ‘solarized-light’ theme. You can see available themes at: Github. If you want to switch theme regenerate the chroma.css file eg with monokai style:
hugo gen chromastyles --style=monokai > chroma.css
And replace chroma.css in themes/jalview/assets/css/.
CSS and Javascript
Should be self explanatory but contact Adrian if anything is confusing. You’ll find both in themes/jalview/assets/.
The Stylesheets are added in the Hugo partial template themes/jalview/layouts/partials/head-meta.html. Note that stylesheets are minified and fingerprinted on all but ‘server’ builds.
Similarly global Javascript is added in themes/jalview/layouts/partials/footer-scripts.html.
(If you decide to bring the JalviewJS page into Hugo you’ll probably want to add the javascript only on that page, but using similar code to footer-scripts.html to take advantage of automatic minification and fingerprinting.)
Useful External Tools
Tables can be painful to create in both HTML and Markdown, this may be helpful: