Editing guide

Editing guide for the CEDA website

Introduction  

This site is built with a the Hugo static site builder using the Hinode theme, with styling customised for CEDA. This guide covers how to edit and update the various sections of the site.

Site layout  

Content is organised into the following main sections:

• News
• Events
• Projects
• About

and is written in Markdown format, but with a few extra features provided by both Hugo and the Hinode theme template. It is worth reading the documentation for both of these to understand the syntax fully.

Two further links in the site’s navbar point to components whose content is managed elsewhere:

• Status
  • CEDA/JASMIN service status: this page is a single-page section of this site that renders a JSON feed of events, content for which is stored in the ceda-status repository.
• Techblog
  • an external link to the separately-hosted CEDA TechBlog, maintained here

The site uses a system of templates to transform content in markdown format, into a set of static web pages. So all the different views of the site are pre-generated. So instead of there being an “admin” interface to edit the website as with previous platforms, editing is done by changing/adding to the source content, or modifying templates or configuration, then re-building the site.

Overview of publishing process  

New content gets published when the site is rebuilt. The site gets rebuilt when:

• changes are pushed or merged to the main branch of the repository
• on a schedule, once every weekday night.

After initial setup, the edit/update process involves:

1. pulling the latest changes to the site repo into your local copy (VSCode can do this for you)
2. making a branch for your edits
3. making some changes (e.g. adding a new news item)
4. checking that a LOCAL preview of the site looks OK with your changes
5. committing your changes to your branch (in the version of your repo)
6. pushing that branch to the remote repository (Github)
7. checking that a REMOTE preview of the site looks OK with your changes (a remote preview is generated for each branch automatically)
8. creating a pull request to merge that branch into main
9. reviewing the pull request, see roles
10. merging the pull request, see roles
11. waiting for the site to be rebuilt
12. checking that all is OK with the rebuilt live site

Roles  

The following roles are in use for this site (corresponding to groups in our GitHub org). Your GitHub ID needs to be a member of the relevant group(s).

• ceda-div-site-authors
  • can create content for review & publication by an editor
• ceda-div-site-editors
  • can merge changes for publication to the live site

Editing a news item  

Your route to editing a news item will depend on your role:

• Authors might prefer to create/edit new news items in the GitHub site itself, submitting them for review and publication by an Editor
  • see this process in detail
• Editors would do the whole process themselves, using a local install of Hugo and Hinode to work on changes to the site, or reviewing and merging changes proposed by an editor. They might ask another Editor to review their own changes.
  • see this process in detail

News items are stored in the directory content/news/updates/YYYY where YYYY is the current year.

There is a template news item here, which can be copied as an example:

content/news/updates/2024/2024-03-06-an-example-news-item.md

But to do this, note the following:

• the filename should be of the form YYYY-MM-DD-slug.md, where
  • YYYY-MM-DD is the publication date. If the year is 2024, this file should go in the 2024 directory.
  • slug is a CONCISE string representing the title (doesn’t have to be identical)
  • .md format extension needs to be present, but is not used in the eventual URL of the article

Inside the markdown file we have:

---
title: An example news item
date: 2024-03-06 10:30:00
tags: ['news', 'ceda']
thumbnail: 
icon: fas circle-info text-info
draft: true # remove this line in your copy
---

No need to repeat the title as a heading here.
This is an example news item which can be copied to create a new one.

### Here's a heading

Here's some text (after a spacer line)

#### A subheading

And some more text, just before the blank line at the end.

Looking at the top section first:

• The “Frontmatter” or metadata section is at the top of the file, between the separators --- and ---. Hugo allows frontmatter in YAML, TOML or JSON syntax: the separator symbol denotes which: --- is for YAML. For this site, to keep things simple, we’ll stick to YAML as used above.
• There should be a blank line after the separator and before the markdown content, and also at the end of the file (see markdown-source-files).

For a full explanation see the documentation on Hinode Frontmatter, but the Frontmatter fields used above (and sufficient for a simple news item) are:

Once the rest of the content of the news item has been written, you’re at step 3 of the publishing process, so follow the remainder of the process to get the item published.

What is markdown?  

Markdown is very lightweight markup language for creating formatted text. It’s intended to be easy to read in its basic form, but the Hugo and Hinode systems used here add some additional functionality by using shortcodes and other features, which help specifically in the creation of richly-formatted static websites.

Style guidelines  

We want to keep the site looking smart, engaging and easy to read.

By using a well-maintained set of tools and taking care with authoring, reviewing and publishing content on the site, this is now more achievable than with previous platforms, using the tips and guidelines below.

Markdown source files  

• VSCode supports editing and preview of markdown files without installing anything new
  • good for a basic, quick view and for proofreading
• Install and use the David Anson / markdownlint markdown linter for VScode
  • this helps keep markdown content tidy and functional
  • for example: preferred syntax for lists, whitespace, headings, etc.
  • (rather than list all the rules here, use the linter and discover better markdown syntax!)
  • it doesn’t support ALL the formatting we might want to use, but we could extend the rule set. Exemptions can be declared (see source for this article, around the example shortcode)
• Managing the source content using git we have better control of the process
  • Use VSCode’s git integrations to help with managing your changes to the site

Content  

General  

• Be concise 😉

Links  

• Use labelled links instead of describing what to do: avoid “please follow the link below”
• Use
  buttons
    to make important links or actions visually distinct
• In-page links are automatically generated from subheadings (hover to see them), so don’t make your own.
• Use the link shortcode where possible, as this makes it easier to control their appearance throughout the site. But if you can’t bothered, the [markdown](#url) format works too.
• You can link to things by name, slug, url or (if needed) path to the markdown file. See the link documentation for examples.
• Use a relative link if at all possible, this makes changes to the site easier
• There’s a curated set of frequently-used links (e.g. "ceda_archive") in config/_default/params.toml: consider adding to this list for frequently-used links: this means they can be used throughout the site but updated in one place if things change.
• We can create a curated set of abbreviations, stored in data/abbr.yml, for use with the abbr shortcode, for example ceda (hover for details).

Images  

(see Hinode docs)

Hinode has some clever image-formatting features, see Hinode docs for details.

Store images for a news item post in assets/img/YYYY/YYYY-slug/ and choose one of them as the thumbnail. Others can be referred to in the text using the image shortcode, e.g.

{{< image src="img/flowers.jpg" ratio="3x2" caption="image caption" >}}

Note that although the image is stored below assets/img, the path starts with img/ for the shortode. Add captions. Read the docs for why. Use wrapper classes to control the size & how the image is displayed.

Code and commands  

Hugo supports Chroma syntax-highlighting of a huge list of languages, and Hinode provides shortcodes for some of these. Use the command-prompt or example shortcodes to render examples smartly,

export MY_VAR=123 # comment
command output

{{< command user="user" host="sci1" >}}
export MY_VAR=123 ## comment
(out)command output
{{< /command >}}

or use code blocks to apply syntax highlighting.

import something

print("hello world")

Use inline codehighlighting to show paths or filenames like /home/users/<username>.

Some of these features are more suited to documentation (hence also using Hinode for the JASMIN Help Docs site), but if we’re including this sort of information in news items then these features help make it easier to read and more engaging as content.

Other formatting components  

• Use alerts to really grab attention

See the full set of Hinode formatting components for further ideas to brighten up content.

The table of contents shown in the right sidebar of this page is generated automatically from the headings in the markdown, but only for documents in the docs section of the site (not currently linked in the navbar), as these section has a particular layout applied to it, see Hinode documentation on Content Management. Similarly, the left sidebar navigation menu only appeats for the docs section of the site. Its contents is controlled by the file data/docs.yml, see

Editing an event  

Editing a Project  

Editing the About pages  

Making other changes to the site  

Configuration  

Cofiguration files are stored in…

Layouts  

The layouts directory contains…

Initial setup and using VSCode to help with the edit process