Runbooks > Examples > Tips & Tricks

Tips & Tricks

Here we are sharing some tips n tricks specific to using this site and its theme - i.e. not just standard Markdown stuff, but the things that are little bit extra!

Ordering Sections

Use the weight: property to control the order of things - in _index.md this will affect the sections, in pages it will affect the order within the section.

If you prefer to order by page title instead, you can change the setting in config.yaml under params:.

Useful Front Matter

menuTitle:              # can override the sidemenu title. Very useful where your actual title is long and you want a shorter one to not wrap
disableToc: "false"     # turns off the Table of Contents up by the breadcrumbs at the top
hidden: false           # hides the page from the sidebar menu (but still creates it for linking to elsewhere)
enableGitInfo: true     # show last commit message, or not. Defaulted to on

In _index.md (i.e. a chapter/section page) - will ensure that the menu stays open on the left, always:

alwaysopen: true

Image Tricks

Add ?width=Npx and ?height=Npx on end of markdown, like so:

![GCP](images/gcp.png?height=150px&classes=shadow)

Can also specify ?classes=border or ?classes=shadow (customise your CSS to add other options)

Awesome Fonts & Icons

These are available - see here for free tier which can be used: https://fontawesome.com/icons?d=gallery&m=free

Syntax is e.g. I <i class="fas fa-heart"></i> GCP which gives … I GCP

Emoji

Are enabled - use the syntax :emoji-name:, e.g. 😄 Emoji Cheatsheet.

GitInfo

Will be added automatically for “default” documents, because enableGitInfo is set in config.yaml. the config for this is in the theme - ./src/themes./runbooks/layout/_default/single.html

Shortcodes

See the ones built into the original theme here. Additional ones are included within ./src/themes/runbooks/layouts/shortcodes/.

Notices

The notice shortcode is really useful for eye-catching callouts, like warnings. The syntax is as follows:

{{% notice note %}}
Notice goes here - and **markdown** is supported within
{{% /notice %}}

There are a number of colours to choose from - replace note (blue) with info (orange), tip (green) or warning (red):

Note notice. Noiiiice!

Info notice. Inspirational!

Tip notice. Tasty!

Warning notice. Wowzer!

Links to Child Pages

Good to include on chapter landing (_index.md) pages:

{{% children %}}

Adding Buttons

This syntax will produce buttons:

{{% button href="<url-to-link-to>" icon="fas fa-download" %}}A Download Link with icon{{% /button %}}

A Download Link

Expand / Spoiler Tags

{{%expand "Click to show Hidden Content" %}}Here is some additional text hidden behind an expansion dropdown{{% /expand %}}

Click to show Hidden Content

Flowcharts, Simple Diagrams, etc

It is possible to draw simple diagrams, like Flowcharts, Sequence Diagrams and good ol' GANTT charts if you desire, using the Mermaid plugin. Rather than reproduce the guide here, see this page for more detail on how.

Their first example to confirm it works is shown here:

{{%mermaid align="left"%}}
graph LR;
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]
{{% /mermaid %}}

graph LR; A[Hard edge] -->|Link text| B(Round edge) B --> C{Decision} C -->|One| D[Result one] C -->|Two| E[Result two]

Asciinema

{{<asciinema key="examples/demo" rows="10" preload="1">}}

… where the cast you’ve saved is called demo.cast, and it is saved in the examples/ sub-directory under content/.

YouTube

{{<youtube id="G1IbRujko-A" title="Gandalf">}}

Gist

{{<gist alexdmoss e1b1c7e94b9339e855b60f8152613bba>}}

Github

{{<github repo="alexdmoss/runbooks" file=".markdownlint.json" lang="json" options="">}}

1
2
3
4
5
6
7
8
9


{
    "default": true,
    "no-bare-urls": false,
    "line-length": false,
    "single-h1": false,
    "no-trailing-punctuation": false,
    "no-inline-html": false,
    "no-emphasis-as-heading": false
}