micafer/documentation

Sources to build EGI documentation site.

EGI documentation

Sources 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 using a dedicated GitHub repository.

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

Requirements

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

Installing dependencies, building and testing locally

Hugo can be installed following the official documentation.

Hugo (extended) releases can be downloaded at the Hugo releases page.

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

Building the site

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

Testing the site locally

# From the repository clone root
hugo server -D

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

Updating the theme

To ease 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 to main, it will then be available at https://docs.egi.eu.