GBIF Training Courses

This is the source code for the GBIF training courses site.

There is also a development site.

Note	This file is documenting the training course site system, it’s not shown on https://training.gbif.org/.

Overall structure

The system uses Antora, a framework for combining documentation written in Asciidoctor from multiple Git repositories into a single documentation website.

Languages, components, versions and modules

Antora strictly defines how files and directories should be arranged, but flexible in allowing those files and directories to come from various sources. There are four levels of content:

Languages

(GBIF addition, but following the suggestion on the Antora issue tracker). We don’t expect all the courses to be translated into every language, so we should structure content to make it easy for translators to translate (and see progress) for suitable topics without being overwhelmed.

Components

Self-contained courses, e.g. Global Nodes or Nodes Training.

Versions

Each component can optionally have one or more versions. We should only declare versions where it makes sense to keep old courses accessible online.

Modules

Antora describes modules as "primarily an organization tool for the writer". So far we haven’t used them, so everything is using the default ROOT module.

Each language has its own playbook. Each playbook specifies which components and versions are part of the documentation. See training-en-playbook.yml for the English playbook. The content.sources with a url of . are in this Git repository, and HEAD shows the current (i.e. main) branch is used to provide a single version. The other components ([email protected]…) are from other Git repositories, and some have multiple versions shown in branches.

Determining how individual pages should be arranged into components (and potentially modules) is not clear. It may make translators' work easier if they can aim to translate entire components/modules.

Within a component version

A version of a component is defined by its antora.yml descriptor file, which should be present at the location specified in {url}/{start_path} from the playbook’s content.sources section. For example, the Global Nodes component has its descriptor file in this repository at en/global-nodes/antora.yml:

name: global-nodes
title: Global Nodes
version: ~
nav:
- modules/ROOT/nav.adoc

The name is the identifier for the component used in links and URLs. The title is used for display. A version of ~ means "no versions".

nav sets the left-bar navigation menu. The content of the linked file is an Asciidoctor unordered list.

Further reading

It’s probably worth looking at these pages in the Antora and Asciidoctor documentation:

• Family directories, to see where files for individual pages, images, attachments (downloads) etc. should be stored

• Xref macros and page links and create page links to see how to make links within a page, between pages in the same module, different modules, different versions and different components.

• The Antora documentation and the Asciidoctor documentation.

Special pages

Home page

The English home page, https://training.gbif.org/en/, is a component called ROOT, which is a special name where ROOT doesn’t show in links or URLs. Reserve pages in this section for the home page and very general pages about all the training courses.

Site theme

The overall design of the site is controlled by a theme, tech-docs-theme. That sets the colours, fonts etc and adds the "Search" functionality.

Changing the site menus (on the green bar) is done by overriding the theme. Start at supplemental_ui/partials/header-navigation.hbs and copy + paste until you have what you want :-) (but remember pushing changes rebuilds the live site).

Language setup

Translations are managed using Crowdin, in the GBIF Training Courses project. The Jenkins build creates and updates the necessary files.

Languages enabled for deployment to https://training.gbif.org/ are configured within Jenkins. If new languages are enabled, the header-languages.hbs and head-styles.hbs files should be updated too.

Building

The site builds in Jenkins every time it is modified, see the status and badge above. To build it locally, the simplest method is to use Docker. See the Docker documentation for installation on Linux, Mac and Windows.

For routine use when authoring courses, build just the English courses and omit the search functionality. This uses a special cut-down playbook without some of the configuration suitable for a webserver:

./build-local-documentation.sh

To build English and Spanish and with the search function, and suitable for a webserver, run:

docker run --rm -t --user $(id -u) --volume $PWD:/antora:Z --env HOME=/antora antora/antora:3.0.1 npm i @antora/lunr-extension
for lang in en es; do
    docker run --rm -t --user $(id -u) --volume $PWD:/antora:Z antora/antora:3.0.1 training-$lang-playbook.yml
done

Please explore the Antora documentation for alternative methods for building, but they are all going to be more effort than installing Docker.