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:
[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:
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:¶
``` php
<?php
$example = (new CodeHilite())->blah();
```
Result:¶
<?php
$example = (new CodeHilite())->blah();
InlineHilite¶
To highlight inline code segments as opposed to blocks
Example:¶
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