Formatting

CLICK TO VIEW THIS PAGE RENDERED IN MKDOCS

Headers¶

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.

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, this usually happens around 32-ish characters however this will vary depending on the letters being used.

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.

Text Emphasis¶

bold: **bold**

italic: _italic

Tab Containers¶

Tab OneTab two

something in the tab

something else

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

Admonitions¶

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.

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

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

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.

Pied-piper

don't use this (unless Dini).

Desktop-download-24

don't use this (unless Dini).

Magnifying-glass

don't use this (unless Dini).

Microscope

don't use this (unless Dini).

Vial-virus

don't use this (unless Dini).

Database

don't use this (unless Dini).

Folder-open

don't use this (unless Dini).

Backward

don't use this (unless Dini).

Jupyter

don't use this (unless Dini).

Terminal

don't use this (unless Dini).

R-project

don't use this (unless Dini).

Calendar-days

don't use this (unless Dini).

Bell

don't use this (unless Dini).

Comment-dots

don't use this (unless Dini).

Check-to-slot

don't use this (unless Dini).

Square-xmark

don't use this (unless Dini).

Rectangle-list

don't use this (unless Dini).

Screwdriver-wrench

don't use this (unless Dini).

Linux

don't use this (unless Dini).

Code-compare

don't use this (unless Dini).

Heading

don't use this (unless Dini).

Space-awesome

don't use this (unless Dini).

Stethoscope

don't use this (unless Dini).

Key

don't use this (unless Dini).

Users-line

don't use this (unless Dini).

File-code

don't use this (unless Dini).

Hand-holding-dollar

don't use this (unless Dini).

Circle-question

don't use this (unless Dini).

Microphone

don't use this (unless Dini).

Tower-observation

don't use this (unless Dini).

Circle-info

don't use this (unless Dini).

Icon--python

don't use this (unless Dini).

Quote-right

don't use this (unless Dini).

Image

don't use this (unless Dini).

Table

don't use this (unless Dini).

Glass-chart

don't use this (unless Dini).

File-export

don't use this (unless Dini).

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.

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 if this is something we want it should be added through formatting, not text.

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.

Images¶

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

This is an image

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.

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.

Links¶

External Link

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

Internal Link

[Internal Link]("General/FAQs/Password_Expiry")

Warning

Link paths are relative to current file!!!

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, 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).

Tooltips¶

Hover over me

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

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

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

Lists¶

Unordered List¶

item1
item2
a
item

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

Ordered List¶

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

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

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	Center	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' %}

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/appHeader.html" %}`	Info block	At the top of documents about particular software (TODO: elaborate)
`{% include "partials/app/app_network_licence.html" %}`	List of network licences	When dynamic licence info is required (used in `appHeader.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

`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-4.2.0
ase-3.22.1
biom-format-2.1.12
biopython-1.79
bokeh-2.4.3
Bottleneck-1.3.4
cftime-1.6.0
click-8.0.3
click-plugins-1.1.1
colorcet-3.0.0
Cython-0.29.30
dask-2022.5.2
dask-jobqueue-0.7.3
dask-mpi-2022.4.0
datashader-0.14.0
datashape-0.5.2
decorator-5.1.1
DendroPy-4.5.2
distlib-0.3.4
docopt-ng-0.8.1
flake8-black-0.3.3
future-0.18.2
h5py-3.7.0
hdf5storage-0.1.18
holoviews-1.14.9
HTSeq-2.0.1
hvplot-0.8.0
ipython-8.4.0
ipywidgets-7.7.0
joblib-1.1.0
kiwisolver-1.3.2
liac-arff-2.5.0
llvmlite-0.38.1
lockfile-0.12.2
lxml-4.9.0
Mako-1.1.6
Markdown-3.3.7
matplotlib-3.5.2
mpi4py-3.1.3
mpmath-1.2.1
NeSI-1.0
netCDF4-1.5.8
networkx-2.8.4
numba-0.55.2
numexpr_fakename-2.8.1
numpy-1.22.4
obspy-1.3.0
openpyxl-3.0.9
pandas-1.4.2
panel-0.13.1
patsy-0.5.2
paycheck-1.0.2
Pillow-9.1.1
pipenv-2022.5.2
plotly-5.8.2
poetry-core-1.0.8
prettytable-3.3.0
psycopg-3.0.15
psycopg2-binary-2.9.3
pudb-2022.1.1
py-spy-0.3.11
Py6S-1.9.1
pybedtools-0.9.0
pyct-0.4.8
PYPIpybind11-2.9.2
pysam-0.19.1
pysolar-0.10
pytest-7.1.2
python-dateutil-2.8.2
pythran-0.11.0
pytz_deprecation_shim-0.1.0.post0
pyviz_comms-2.2.0
qutip-4.7.0
reportlab-3.6.9
requests-2.27.1
rich-12.4.4
scalene-1.5.8
scikit-bio-0.5.7
scikit-image-0.19.2
scikit-learn-1.1.1
scipy-1.8.1
seaborn-0.11.2
six-1.16.0
SQLAlchemy-1.4.28
statsmodels-0.13.2
streamlit-1.10.0
sympy-1.10.1
tabulate-0.8.9
tqdm-4.64.0
tzdata-2022.1
tzlocal-4.2
virtualenv-20.14.1
wheel-0.37.1
xarray-2022.3.0
xlrd-2.0.1

Our Python modules come pre-built with the following packages:
<table>
<tr><th>Package</th></tr>
{% for pyext in applications.Python.extensions %}
<tr><td>{{ pyext }}</td></tr>
{% endfor %}
</table>