Mahuika support documentation

This repository contains the sources files for the Mahuika support documentation.

Rendered pages are visible at https://docs.nesi.org.nz.

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 writing principles (local version), for what to write, whether to write it, and how much.
• See create a new page, for page structure, metadata, naming and tags.
• 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

Every pull request is built and deployed to a preview site by demo_deploy.yml. A comment on the pull request links to the preview and to each changed page.

Previews are at https://callumwalley.github.io/mkdocs-demo-deploy/nesi/support-docs/NAME-OF-BRANCH, and all of them are listed at https://callumwalley.github.io/mkdocs-demo-deploy.

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. To run locally:

mkdocs serve -c

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. ↩