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¶
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 
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"/>
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
Admonitions / Notes¶
Basic¶
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, now as pretty as our custom no title unlike
previous versions.
!!! 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
A user or academic
User/academic using quote admonition
Package all the things!
Storage/application using example admonition
Expandable¶
expandable admonition (click to hide)
this is a test
expandable admonition (click to expand)
this is a test
expandable admonition (click to expand)
some text
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 |
Links in tables¶
To highlight links in tables we add this icon:
| 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()
Displaying a code block inside an admonition (via super fences):
testing a code block inside an admonition
This is some text.
This is some code
This is more text.
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="fas fa-camera-retro fa-lg"></i>
<i class="fas fa-camera-retro fa-2x"></i>
<i class="fas fa-camera-retro fa-3x"></i>
<i class="fas fa-camera-retro fa-4x"></i>
<i class="fas fa-camera-retro fa-5x"></i>
<i class="fas fa-microchip fa-lg"></i>
<i class="fas fa-microchip fa-2x"></i>
<i class="fas fa-microchip fa-3x"></i>
<i class="fas fa-microchip fa-4x"></i>
<i class="fas fa-microchip fa-5x"></i>
<i class="fas fa-motorcycle fa-lg"></i>
<i class="fas fa-motorcycle fa-2x"></i>
<i class="fas fa-motorcycle fa-3x"></i>
<i class="fas fa-motorcycle fa-4x"></i>
<i class="fas fa-motorcycle fa-5x"></i>
<i class="fab fa-empire fa-lg"></i>
<i class="fab fa-empire fa-2x"></i>
<i class="fab fa-empire fa-3x"></i>
<i class="fab fa-empire fa-4x"></i>
<i class="fab fa-empire fa-5x"></i>
Spinning¶
<i class="fas 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.