NeSI support documentation

NeSI docs template

Replace this readme with info about the site.

First Time Setup

You will need to have Python 3.10 or later installed on your computer.

Clone this repository and create a Python virtual environment using:

git clone https://github.com/nesi/nesi-mkdoc-template.git
cd nesi-mkdoc-template
python -m venv .venv
source .venv/bin/activate
pip3 install pip-tools
pip-compile
pip3 install -r requirements.txt

Build and deploy

source .venv/bin/activate
mkdocs serve -c

Take note of any warnings or errors.

A link to the deployment will be printed once served

Contents

The repository is organised using the following folders:

• checks : scripts intended to be run by CI,
• docs: markdown files, structure determines categories and sections¹,
• docs/assets: non-template related files, e.g. images,
• overrides: theme overides or extensions for page templates.
• overrides/partials: Overrides and extensions for sub components.

Developer Documentation

Following pages contain information to help maintain the documentation:

• See contributing (local version), to learn how to you can contribute.
• See formatting, for examples of markdown syntax.
• See create a new page, for general principles to consider when writing pages.
• See macros, for mkdocs-macros-plugin environment.
• See checks, for information on quality assurance tests.
• See workflows, for information on CI workflows.

Viewing PR Branches

Deployments of open pull requests can be viewed at https://callumwalley.github.io/support-docs-dev/NAME-OF-BRANCH

Theme

We are using the mkdocs material theme.

Analytics

The site uses Google analytics. You will need to ask a google workspace admin to add you to the project.

Updating Dependencies

Occasionally you may want to update the dependencies used by mkdocs to build and lint this site.

Make a new branch and

pip-compile --allow-unsafe > requirements.txt
pip install -r requirements.txt

Make sure to test it on a GitHub runner (not just locally), as this is the actual build environment.

Migration

Migration of the Zendesk documentation is done using our migration pipeline (NeSI internal GitLab.

Any one off filters (e.g. don't need to be checked every time, just when converting from ZD) should go there.

Footnotes

1. A section or category can be replaced by an index.md file, this will replace the default nav with a page. ↩