mkdocs Syntax Tutorial / Sandbox

Text and Blue box headings

Text

Standard text, blank lines create paragraphs.

Please note that the headnodes are rebooted reasonably frequently so interactive jobs should only be used for short tasks. At busy times you may not be able to get an interactive session as there may be no spare cores to immediately service your request.

Bold Text is wrapped in a pair of **asterisks**

Italic Text is wrapped in single *asterisks*

Text can be on one line or two until there is a blank line. it will combine into a sane paragraph

Headings

  • Headings are done with varying numbers of #, you can also use --- or === but we standardise on #.
  • ## (h2) after a --- (hr) is set up to create a blue line across the page for page section headings.
  • To hide from TOC / sidebar use HTML tags <h1>h1</h1>

h1

h2


h2 after hr

h3

h4

h5
h6

Links use [Text](index.md) or [Other](/using)for internal: Text, Other

And [Text2](http://example.com) for external: Text2

Images

Content

Images can be added using ![Example Image](img/blue_racks.jpg)

Example Image

Exact placing can be done using some html hackery, e.g.:

<img src="/img/Octocat.png" alt="Octocat.png" width="320" style="float: right;"/>

No content

Images that are there to make things pretty can be given the nocontentimg class which will float them right and hide them on small screens / print copies.

<img src="/img/srif.png" alt="srif.png" class="nocontentimg"/>

srif.png

This is an example block of text to demonstrate the image setup for nocontentimg I'd use lorem ipsum but that would set off the spell check and we don't want that. If you use responsive design mode in firefox CTRL + Shift + M and alternately decrease and increase the width you can see how this works.

I am now running out of things to say as part of this block of text red blue window tile ceiling floor desk wall. Maybe we could talk about the sky but I can't actually see it from my desk, we've managed windows but not sky. I guess at least there's indirect sunlight and it is occasionally bright but quite often gloomy. Images in text can help make it less gloomy and sometimes can even aid explanation, but those types of images shouldn't use nocontentimg as they'll disappear in print or on small screens.

Bullet points

Bullet points use * e.g.:

    * Test123
    * Test456
        * Sub Test789
    * Test0
  • Test123
  • Test456
    • Sub Test789
  • Test0

Whitespace

You can put whitespace in the page using <br/> make sure to have a blank line either side.

Comments

You can use html comment syntax:

<!-- COMMENT -->

Note that it will show up in the HTML.

Asciicast Embedding

Asciicasts can be embedded by adding this code:

<asciinema-player src="/asciicasts/demo.json"/>

Then dropping the asciicast (demo.json) into the asciicasts folder.

To fix the size changing when the play button is pressed you can specify the height of the player to be the same as the asciicast:

<asciinema-player src="/asciicasts/demo.json" cols=80 rows=24/>

Asciicast 1


Quotes

Quotes from websites etc can be done with:

Here is a quote:

> This is a quote

Here is a multiline quote (note lines are merged if length allows):

> One
> Two
> this is a much longer line to show that lines are auto merged etc, are we at
> the limit yet how about now

Here is a quote:

This is a quote

Here is a multi-line quote (note lines are merged if length allows):

One Two this is a much longer line to show that lines are auto merged etc, are we at the limit yet how about now

Notes / Admonitions

Built-in

Note

This is a note. The syntax is !!! note "Title"

Important Note

An important note.

Warning Note

An warning note.

Off the shelf no title, not as pretty as ours. !!! note ""

Summary

A summary admonition.

A Tip

Use admonitions but not for quotes, use quotes for quotes! tip

A Great Success

Much success

A Disappointing Failure

Failing Fail failure

This may hurt...

Danger! danger

There's a bug!

Bug bug

Custom

Notitle

Custom notitle admonition, prettier than stock

Its a hub for gits

Github admonition github

Its a collection of buildings

QMUL admonition qmul

Its full of students

Academic admonition academic

Users everywhere

User admonition users

Package all the things!

package Packing packages with packs.

Tables

Some things to note:

  • Only column headers
  • No cell merging capability
| First Header | Second Header | Third Header | Left | Right | Centre |
| ------------ | ------------- | ------------ | :--- | ---:  | :---:  |
| Content Cell | Content Cell  | Content Cell | 123  | 123   | 123    |
| Content Cell | Content Cell  | Content Cell | 12   | 12    | 12     |
| Content Cell | Content Cell  | Content Cell | 1211 | 1211  | 1211   |
First Header Second Header Third Header Left Right Centre
Content Cell Content Cell Content Cell 123 123 123
Content Cell Content Cell Content Cell 12 12 12
Content Cell Content Cell Content Cell 1211 1211 1211

To highlight links in tables we add this icon:

link outside

col one col two
one two
not link not link two

Code

Fenced Code sits between 3 backticks

import sys
print(sys.argv[0])

# Get users supposed to be running on node
QSTAT_CMD = "qstat -q *@{} -u \* -g dt"
hostname = os.uname()[1]
qstat_users = subprocess.check_output(QSTAT_CMD.format(hostname), shell=True,
universal_newlines=True)
qstat_users = qstat_users.splitlines()
qstat_users = qstat_users[2:]  # Remove header
qstat_users = [l.split()[3] for l in qstat_users
               if len(l.split()) > 3]  # Select user

You can specify syntax, and should:

SELECT * FROM users;

You can also specify no highlighting:

SELECT * FROM users;

Code inline can be done using code tags: print("test") or backticks print("test2"), backticks being preferred.

You can also highlight specific lines:

import antigravity

def run():
    antigravity.fly()
    print("Flight!")

if __name__ == "__main__":
    run()

Combining multiple pages into one

This can be done by using {!filename!}, make sure to leave blank lines between multiple page includes otherwise weirdness may occur.

Note

Use backslashes to get mkdocs to ignore special characters

Font Awesome

Font awesome is included so we can do stuff like this:

<i class="fa fa-camera-retro fa-lg"></i>
<i class="fa fa-camera-retro fa-2x"></i>
<i class="fa fa-camera-retro fa-3x"></i>
<i class="fa fa-camera-retro fa-4x"></i>
<i class="fa fa-camera-retro fa-5x"></i>

<i class="fa fa-microchip fa-lg"></i>
<i class="fa fa-microchip fa-2x"></i>
<i class="fa fa-microchip fa-3x"></i>
<i class="fa fa-microchip fa-4x"></i>
<i class="fa fa-microchip fa-5x"></i>

<i class="fa fa-motorcycle fa-lg"></i>
<i class="fa fa-motorcycle fa-2x"></i>
<i class="fa fa-motorcycle fa-3x"></i>
<i class="fa fa-motorcycle fa-4x"></i>
<i class="fa fa-motorcycle fa-5x"></i>

<i class="fa fa-empire fa-lg"></i>
<i class="fa fa-empire fa-2x"></i>
<i class="fa fa-empire fa-3x"></i>
<i class="fa fa-empire fa-4x"></i>
<i class="fa fa-empire fa-5x"></i>

Spinning

<i class="fa fa-cog fa-spin fa-3x fa-fw" aria-hidden="true"></i>

Stacking

Spin and stack

See http://fontawesome.io/icons/ for a full list and http://fontawesome.io/examples/ for additional settings.