Markdown Syntax

The system uses standard Markdown Syntax, extended with the following:

Linking to Other Pages In The Docs

The correct and best way to to this is to simply link to the path of the .md file. Mkdocs will correctly create the link and will also let us know if the link is broken.

Eg

where the other document is located in docs/link/to/other/ and is called document.md, the link should be like this:

1
[link text](/link/to/other/document.md)

Admonition

Admonition is an extension included in the standard Markdown library that makes it possible to add block-styled side content to your documentation, for example summaries, notes, hints or warnings.

Note

This is an example of an Admonition block

The block types are:

  • note
  • summary
  • tip
  • success
  • warning
  • failure
  • danger
  • bug

Retraction

To insert a retracted line of text you need to have!!! sensitive-info and then the text underneath indented like so:

link text

CodeHilite

CodeHilite is an extension that adds syntax highlighting to code blocks and is included in the standard Markdown library. The highlighting process is executed during compilation of the Markdown file.

Do the standard three backticks, a space, and then the language

Example:

1
2
3
4
``` php
<?php
$example = (new CodeHilite())->blah();
```

Result:

1
2
<?php
$example = (new CodeHilite())->blah();

InlineHilite

To highlight inline code segments as opposed to blocks

Example:

1
This is a sentence with `#!php <?php echo $example;?>` PHP inline syntax highlighting

Result:

This is a sentence with <?php echo $example;?> PHP inline syntax highlighting