EGI documentation

Source files used to build EGI documentation.

• Hugo is used to build a static site.
• The theme docsy is used.
• The static site is deployed on GitHub by using a dedicated GitHub repository.

If you are interested in contributing, please check the Contributing Guide.

Requirements

• hugo (extended)
• NodeJS and docsy theme dependencies:
  • postcss-cli
  • autoprofixer

These dependencies can be either installed manually or reusing a flox environment. Please see the steps below.

Installing dependencies manually

Hugo can be installed by following the official documentation.

Hugo (extended) releases can be downloaded from the Hugo releases page. The recommended version for Hugo is specified under the GitHub Action in .github/workflows/hugo_version.txt.

To install npm+nodejs please check the official instructions.

Everything has been tested with Node.js 12.

The dependencies of the docsy theme can be installed as follows:

# From the root of the repository clone
npm ci

Reuse the flox environment

Flox is a virtual environment and package manager all in one. We provide a flox environment in our GitHub repository in a way that it is easier for everybody to work with the same software dependencies and contribute to this repository.

After installing flox you can reuse the provided environment with:

# From the root of the repository clone
flox activate
# Then install docsy dependencies with
npm ci

Building the site

# From the root of the repository clone
git submodule update --init --recursive --depth 1
hugo --minify

Testing the site locally

# From the root of the repository clone
hugo server -D

The site is available locally at: http://localhost:1313/.

Updating the theme

For ease of management, the docsy theme has been cloned as a git submodule.

Updating the theme submodule

git submodule foreach git pull
git commit themes/docsy -m 'Update theme'

Deployment to the EGI organisation pages

GitHub Actions will automatically deploy a new version when a PR is merged into main. It will then be available at https://docs.egi.eu.