Formatting

CLICK TO VIEW THIS PAGE RENDERED IN MKDOCS

See also

• To learn how you can contribute, see CONTRIBUTING.
• For information about page creation, see NEWPAGE.
• For what to write, and whether to write it, see PRINCIPLES.

This page is an overview of the naming conventions and Markdown syntax used in this documentation.

Names and terms

• Call the organisation REANNZ.
• Call the platform Mahuika. After the first mention, "the cluster" is fine. Don't use ""HPC3", which was a temporary name.
• Only write NeSI where a name still carries it, for example my.nesi.org.nz, the support email address, hostnames, and the example project code nesi99991.
• For other terms, use the words in the Glossary, so they match the tooltips.

The prose check flags these old names, outside announcements and release notes.

Headers

Headers should be surrounded by blank lines.

H2

## H2

H3

### H3

H4

#### H4

Headers should have a blank line before and after.

Don't use H1 (#) this is reserved for the page title. Setting a title here will change it in the nav also.

Don't start a page with a heading such as "Introduction" or "Overview": the text after the title is the introduction.

Make each heading say what its section is about, with the key word first. Avoid generic headings such as "Description", "Details" or "Summary". Start the heading of a task with a verb, for example "Connect with SSH". Don't write headings as questions: they're hard to front-load, and readers want answers.

Write headings in sentence case: capitalise only the first word and proper nouns. Page titles use Title Case instead, see Article/Category Naming.

These follow GOV.UK's Create a clear structure, the UK Office for National Statistics guide to structuring content, and Google's Headings and titles. The GOV.UK Design System and Google both use sentence case for headings.

h2 and h3 elements will be used to generate a table of contents (toc).

Try to keep headers short enough that they do not 'wrap' (become more than one line) in the toc. The meta check warns when an h2 is over 28 characters or an h3 is over 26, but this will vary depending on the letters being used.

Header boundaries are also how the docs chat assistant splits pages into retrievable chunks, aiming for roughly 400-3200 characters of body text per section. A section outside that band gets silently merged into a neighbour or force-split on a paragraph boundary before being embedded.

Line breaks

Put 2 spaces at the end of a line to force a line break.
If you simply hit enter and don't use 2 spaces it will be considered one line.

Put 2 spaces at the end of a line to force a line break.  
If you simply hit enter and don't use 2 spaces it will be considered one line.

Most markdown structures (lists, Admonitions, headers, code blocks, etc) should be surrounded by an empty line. i.e. A newline before and after. It is good practice to add a new line after every sentence, or when the line becomes too long. This won't change how the text is rendered, but makes the source easier to read, and a change to one sentence shows up as a change to one line in the diff (Semantic Line Breaks).

Text Emphasis

bold: **bold**

italic: _italic_

Tab Containers

Tab Containers should be surrounded by blank lines.

Tab OneTab two

something in the tab

something else

=== "Tab One"
    something in the tab
=== "Tab two"
    something else

Admonitions

Use admonitions sparingly. Too many, especially in a row, stop standing out and get skipped (Google's guide to notes and warnings). Keep warning and danger for real risk, such as lost data or a killed job. Only put something in an info box if a reader who skips it will still succeed.

Admonitions should be surrounded by blank lines.

Warning

A warning.

!!! warning
    A warning.

Admonition Titles

Optional title

Admonition with optional title.

!!! info "Optional title"
    Admonition with optional title.

Adding titles helps users find key information, however if you can't be bothered thinking of a good title, refrain from using something unnecessary or non descriptive (e.g. !!! info "More Information"), better to leave titleless. A good title also helps the docs chat assistant, which shows the admonition kind/title as a label (e.g. **Warning:**) when it surfaces this section as a source.

Don't use a title if another Admonition already exists for that purpose (e.g. !!! info "Watch out!").

Collapsable Admonitions

Any Admonition can be made collapsable by replacing the !!! with ??? (closed), or ???+ (open)

I'm Collapseable

Wheeee

??? info "I'm Collapseable"
    Wheeee

Consider making a Admonition collapsable-open (???+) if it is particularly long. An Admonition shouldn't be made collapsable-closed (???) unless it has been given an optional title explaining it's contents.

Admonition Flavours

There are various flavours.

Prerequisite

• link to page a user should read in order to follow
• some thing other requirement user must have to follow this page
• usually you will want this to be a list format.
• Should be right at the top of the page.

with title

For tangential actionable advice.
x other command may be useful here.

Info

Use this to provide (optional) additional context or make an in depth explanation. A little bit of info that isn't required for understanding the next paragraph.

Warning

Use this to draw readers attention to possible rare or edge case failures they may encounter. If your filesystem is full you might get an error message.

Danger

Use this to draw attention to information that may lead to serious harm if ignored. If your filesystem is full your job might be killed.

Bug

Mention possible bugs users may encounter (and tell them what to do if they encounter it). Nearline doesn't work

Deprecated

Automatically added to pages with the status:deprecated, should be used when page is out of date. This page is rubbish!

30 Minutes (for use in tutorial pages)

Objectives

• For use in tutorials
• learning goal one.
• learning goal two.

Keypoints

• For use in tutorials
• should summarise learning goal one.
• should summarise learning goal two.

Postrequisite

• For use in tutorials
• should link to next lesson.

Extra Admonitions you probably won't need

Note

Use info instead of this.

Question

Havn't seen a reason to use this yet.

Failure

Havn't seen a reason to use this yet.

Example

Havn't seen a reason to use this yet.

Quote

Havn't seen a reason to use this yet.

Code

Block

Code blocks require a language lexer in order to do syntax highlighting, e.g. python ,slurm, cuda, json, markdown, bash (most of these have short codes too, py,sl,cd,md,sh). A full list of lexers can be found in this list. Code blocks should be surrounded by blank lines.

import somepackage

formatting = True
if formatting:
    Print(formatting) # A comment

```py
import somepackage

formatting = True
if formatting:
  Print(formatting) # A comment
```

For plain text code blocks, still good to use a class as descriptor (e.g. txt, stdout, stderr). May want to add formatting to this later.

```stdout
some code
```

some code 

DON'T prefix a command with $ (e.g. $ ls). Commands are easier to copy without it (markdownlint rule MD014). If a prompt is ever wanted, it should be added through formatting, not text.

Keep code lines to about 80 characters, or the block scrolls sideways. The meta check warns about longer lines (allowing a little more in admonitions and a little less in lists). Google's guide to code samples uses the same limit.

Put a command and its output in separate blocks (the output as txt), so the command can be copied on its own.

Values to replace

When a command or script needs the reader's own details, use the standard example values, so every page reads the same:

Value	Example
Username	username
Project code	nesi99991
Project directory	/nesi/project/nesi99991/my_data

For anything else, name the value in capitals with underscores, for example INPUT_FILE. Don't use angle brackets such as <username>: copied unchanged, a shell reads < and > as redirects. Don't use XXXX either.

Straight after the block, say what to replace, for example "Replace nesi99991 with your project code." For two or more values, start a list with "Replace the following:". This follows Google's guide to placeholders.

Inline

This is some echo "Inline Code".

This is some `echo "Inline Code"`.

Inline code does not have syntax highlighting. Code should be used for any text that you want the user to copy exactly.

Keyboard

Keyboard keys can be added using the <kbd> tag.

Press <kbd>ctrl</kbd> + <kbd>c</kbd> to copy text from terminal.

Press <kbd>ctrl</kbd> + <kbd>c</kbd> to copy text from terminal.

Note the additional spacing around the + else it will appear cramped.

Slurm Scripts

The most common use of a code block is to display an example Slurm script.

We want our examples to be easy to understand, but also users will copy paste them, so we also want them to be working scripts that wont cause easily avoidable errors.

If possible stick to the following principles.

• Make sure the code block has the sl language tag. This will inform syntax highlight an CI checks.
• Use #!/bin/bash -e as your shebang.
• One blank line between shebang and Slurm Header.
• Use whitespace for your Slurm header delimiter (preferably aligned in a tidy way).
• Use the long form of Slurm options, e.g. --job-name rather than -J.
• Make sure to include --job-name, --account (nesi99991) and --time.
• One blank line after Slurm header.
• Always module purge before module load.
• Include version in module load. See Variable Injection for convenience macro.
• Don't be too fancy. We all know you are very clever, but your script examples should do the bare minimum needed to provide a safe example.
• If possible, include an example that will work for the user, e.g. one of the tutorial files. (wget, $EB_ROOT, etc)

Example

```sl
#!/bin/bash -e

#SBATCH --job-name          test-job
#SBATCH --account          nesi99991
#SBATCH --time             01:00:00 

module purge
module load MATLAB/{{ applications.MATLAB.default }}

matlab -batch "myScript"    # Some nice informative comment.
```

Images

![This is an image](./assets/images/ANSYS_0.png)

Pasting from Clipboard

You can 'paste' an image from the clipboard into a markdown document, it will add

![Alt text](image.png)

In markdown where you pasted the image, and upload image.png, into the same directory.

Make sure you rename the image.png to something more descriptive, move it into the 'assets/images' folder, and update then markdown accordingly.

Write a real alt text too, not just the filename. The docs chat assistant has no way to see the image itself - the alt text is the only information it gets. The alt text should be written as if no image is visible at all. This is required by WCAG 1.1.1 Non-text Content, and the prose check flags placeholders such as alt text or a file name.

Drag and Drop

You can easily get the path to a image file by dragging it from the left hand Explorer panel over your document, then pressing shift (you will be prompted) and dropping the image in the desired position. Copy pasting an image from Explorer into markdown also works.

You can also start typing ! and then use context suggestions (ctrl + space), select 'Insert Image' and navigate the rest of the way.

Screenshots, diagrams and video

• Only use a screenshot when words can't do the job. Screenshots of web pages go out of date (see Principles).
• Crop screenshots to what matters, and check they don't show real usernames, project codes, email addresses, job IDs or file paths. The site is public.
• A Mermaid diagram has no alt text, so say what it shows in the text next to it (WCAG 1.1.1 Non-text Content).
• Only embed a video that has accurate captions (WCAG 1.2.2 Captions), and give its iframe a title that says what the video is.

Links

External Link

[External Link](https://example.com)

Internal Link

[Internal Link](Storage/Filesystems_and_Quotas.md)

Warning

Link paths are relative to the current file, and point at the .md file, for example ../Storage/Filesystems_and_Quotas.md from a page in Batch_Computing/. Don't link to pages on this site with a full https://docs.nesi.org.nz/... URL. The build can't check those, so it won't catch a broken one (the meta check warns about them).

Anchor Link

[Anchor Link](#links)

snake-case anchors are automatically generated for all headers.

The anchor will be the same as the header text with all non-alphanumeric characters removed, converted to lower case, and space characters replaced with -. For example a header ## This is my (nasty-Header) can be linked to with the anchor [Anchor Link](#this-is-my-nastyheader)

Drag and Drop

You can drag files from the left hand Explorer panel over your document then press shift (you will be prompted) and drop in the desired position. Copy pasting a file from Explorer into markdown also works.

Ambiguous links

Try to avoid putting links on ambiguous words. Link text should say where the link goes (WCAG 2.4.4 Link Purpose), e.g.

BadBetter

View the software homepage here.

View the homepage [here](https://www.example.com).

View the software homepage.

View the [software homepage](https://www.example.com).

Links to schedmd docs

Rather than linking the most up to date version of the Slurm docs, we want to link to the version used by our current Slurm.

Instead of

[sacct](https://slurm.schedmd.com/sacct.html#lbAI)

Use

[sacct](https://slurm.schedmd.com/archive/{{config.extra.slurm}}/sacct.html#lbAI)

The version is set at build time from docs/assets/slurm-limits.json, which is fetched from modules-list, so don't change it by hand. If links to the Slurm docs break after a Slurm upgrade, check that the version is listed in the archive at https://slurm.schedmd.com/archive/.

Tooltips

Only use a tooltip for extra detail. Tooltips show on mouse hover, so keyboard and touch users don't see them.

Hover over me

[Hover over me](https://example.com "I'm a link with a custom tooltip.")

Acronyms should be automatically made tool-tips e.g. MPI.

Acronyms should be automatically made tool-tips e.g. MPI.

Lists

As with other markdown structures, lists must be surrounded by a blank line.

Indent nested items and continuation lines by 4 spaces. With fewer, the items render as one flat list.

Unordered List

some text

• item1
• item2
• a multi-line item
• nested
  • items
    • nested-er

some other text

some text

- item1
- item2
- a
    multi-line
    item
- nested
    - items
        - nested-er

some other text

Ordered List

some text

1. item1
2. a multi-line item with multiple lines
3. nested
   1. nested item 1
   2. nested item 2
      1. even nested-er

some other text

some text

1. item1
2. a
    multi-line
    item
    with multiple
    lines
3. nested
    1. nested item 1
    2. nested item 2
        1. even nested-er

some other text

Note, nested list items use numbers, but will be rendered as whatever the indent is.

Tables

Markdown Table Generator, is a handy tool for complex tables/

Tables can be constructed using | to separate columns, and -- to designate headers.

Number of dashes has no effect, things don't have to be lined up when in markdown, just looks nice. Leading and trailing | are optional.

Head	Head
Thing1	Thing2
Thing3	Thing3

 Head | Head
 --- | -----------
 Thing1 | Thing2
 Thing3 | Thing 3

:'s can be used to align tables.

Left	Centre	Right
Words	Words	Words
Words	Words	Words

| Syntax      | Description | Test Text     |
| :---        |    :----:   |          ---: |
| Header      | Title       | Here's this   |
| Paragraph   | Text        | And more      |

Macros

Macros allow use of Jinja filter syntax inside the markdown files allowing for much more flexible templating. More details can be found on the mkdocs-macros-plugin page.

Includes

The macro plugin allows the use of 'includes', here is an example.

{% include 'snippet.md' %}

{% include %} fails soft in this project: if the included template errors while rendering (e.g. an app is missing an expected field in module-list.json), that include renders as nothing instead of taking out the whole page. No special syntax needed - this is patched into both Jinja environments in mkdocs_hooks.py.

There are a few includes you may want to use.

Path	content	usage
{% include "partials/support_request.html" %}	<a href="mailto:support@nesi.org.nz">Contact our Support Team</a>	Anywhere the user is told to contact support.
{% include "partials/app_header.html" %}	Description, homepage, warnings, module versions and licences for an application	At the top of pages in Software/Available_Applications/, inside the "apps page boilerplate" (needs app_name and app set first)
{% include "partials/app/app_network_licence.html" %}	List of network licences	When dynamic licence info is required (used in app_header.html)
{% include "partials/app/app_version.html" %}	List of versions and a 'module load' code-block.	When dynamic version info is required

Variables injection

Here is an example using dynamically using the module version information.

module load ANSYS/19.2

```sh
module load ANSYS/{{ applications.ANSYS.default }}

```

Advanced Macros

And here is another example showing all Python packages installed in Python modules.

Fancy Example

Our Python modules come pre-built with the following packages:

Package
altair-6.1.0
ase-3.28.0
biom-format-2.1.17
biopython-1.87
bokeh-3.9.0
Bottleneck-1.6.0
cffi-2.0.0
cftime-1.6.5
click-8.3.3
click-plugins-1.1.1.2
colorcet-3.2.1
cppy-1.3.1
cython-3.2.4
dask-2026.3.0
dask-jobqueue-0.9.0
dask-mpi-2026.3.0
datashader-0.19.0
deap-1.4.4
decorator-5.2.1
defopt-7.0.0
DendroPy-5.0.8
distlib-0.4.0
docopt_ng-0.9.0
expecttest-0.3.0
flake8-black-0.4.0
flit_core-3.12.0
h5py-3.16.0
hatch_vcs-0.5.0
hatchling-1.29.0
hdf5storage-0.2.2
holoviews-1.22.1
HTSeq-2.1.2
hvplot-0.12.2
hypothesis-6.152.4
ipython-9.12.0
ipywidgets-8.1.8
joblib-1.5.3
kiwisolver-1.5.0
liac-arff-2.5.0
llvmlite-0.47.0
lxml-6.1.0
Mako-1.3.11
Markdown-3.10.2
matplotlib-3.10.8
meson-1.10.2
meson_python-0.19.0
mpi4py-4.1.1
mpmath-1.4.1
netCDF4-1.7.4
networkx-3.6.1
numba-0.65.1
numexpr-2.14.1
numpy-2.4.4
obspy-1.5.0
openpyxl-3.1.5
packaging-26.2
pandas-3.0.2
panel-1.8.10
param-2.3.3
pathspec-1.1.1
patsy-1.0.2
pillow-12.2.0
pipenv-2026.6.1
plotly-6.7.0
pluggy-1.6.0
poetry_core-2.3.2
polars-1.40.1
prettytable-3.17.0
psycopg-3.3.3
pudb-2025.1.5
py-spy-0.4.2
py4vasp-core-0.11.2
Py6S-1.9.2
pyarrow-24.0.0
pybedtools-0.12.0
pycparser-2.21
pyct-0.6.0
pyls-flake8-0.4.0
PYPIpybind11-3.0.4
pyproject_metadata-0.11.0
pysam-0.24.0
pyshp-3.0.3
pysolar-0.13
pytest-9.0.2
python-dateutil-2.8.2
pythran-0.18.1
pyviz-comms-3.0.6
qutip-5.2.3
reportlab-4.4.10
requests-2.33.1
rich-15.0.0
scalene-2.2.1
scikit-bio-0.7.2
scikit-build-core-0.12.2
scikit-image-0.26.0
scikit-learn-1.8.0
scikit-umfpack-0.4.2
scipy-1.17.1
seaborn-0.13.2
setuptools-82.0.1
setuptools-rust-1.12.1
setuptools_scm-10.0.5
SQLAlchemy-2.0.49
statsmodels-0.14.6
streamlit-1.57.0
sympy-1.14.0
tabulate-0.10.0
tqdm-4.67.3
trove_classifiers-2026.1.14.14
tzdata-2026.1
tzlocal-5.3.1
versioneer-0.29
virtualenv-21.2.4
xarray-2026.4.0
xyzservices-2026.3.0

```md

Our Python modules come pre-built with the following packages:

{% for pyext in applications.Python.extensions %} {% endfor %}

Package
{{ pyext }}

```

Quiz Progress

• Answered: 0 / 0 (0%)
• Correct: 0 / 0 (0%) Reset