Mkdocs

This blog is made with a python library called mkdocs, or more specifically using mkdocs-material which is a fantastic theme that can render markdown files into a pretty website.

Resources¶

Material for MkDocs - The theme being used
PyMdown Extensions - Tons of fancy stuff like banners, emojis and much much more

Abbreviations¶

Define abbreviations to have them automatically annotated throughout the document

Example

The HTML specification is maintained by the W3C.

The HTML specification is maintained by the W3C.
*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Abbreviations Docs

Footnotes¶

Create footnotes inline and have them rendered at the bottom of the page

Example

See example¹

See example[^1]
[^1]: And back to where you were

Footnotes Docs

Admonitions¶

Attention grabbing banners for easy reading

Collapsible

Starts expanded, but can be collapsed

???+ example "Collapsible"
    Your note here

Expandable - Expand Me!

Great for spoilers

??? example "Expandable - Expand Me!"
    Your note here

Warning

This is a warning

!!! warning
    Your note here

Putting a string wrapped in "" after the level (eg. warning) changes the title

There's way more than just example and warning so make sure to check out:

Admonition Docs

Emojis¶

Add a splash of colour

Example

:smile:
:material-account-circle:
:fontawesome-regular-laugh-wink:
:fontawesome-brands-twitter:

Icons + Emojis Docs

Keyboard Keys¶

Unambiguously show keyboard combinations

Example

Ctrl+Alt+Del

++ctrl+alt+del++

Keys Docs

Task Lists¶

Show a checklist of tasks that need doing

Lorem ipsum dolor sit amet, consectetur adipiscing elit
Vestibulum convallis sit amet nisi a tincidunt
- In hac habitasse platea dictumst
- In scelerisque nibh non dolor mollis congue sed et metus
- Praesent sed risus massa
Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

Tasklist Docs

Another related topic is Progress Bars

Code Blocks¶

Standard syntax lighting code blocks, with a copy to clipboard button

```python
print("Hello!")
```

Result

print("Hello!")

Line Numbers¶

``` python linenums="1"

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Highlighting Lines¶

``` python hl_lines="2 3"

def bubble_sort(items):
    for i in range(len(items)):
        for j in range(len(items) - 1 - i):
            if items[j] > items[j + 1]:
                items[j], items[j + 1] = items[j + 1], items[j]

Code Block in Admonition¶

Nest to your heart's content

Example

the_level.pull()

For all information about code-blocks, nesting etc see:
Superfences Docs

Content Tabs¶

Have multiple tabs of content for easy organisation

C

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

C++

#include <iostream>

int main(void) {
  std::cout << "Hello world!" << std::endl;
  return 0;
}

Tabs Docs

Graphs¶

Note

Some of the graph lines are hard to see in dark theme, you can change themes with the button next to the search bar

Sometimes you want to visually show something, and you don't want to leave your editor.

Or maybe you just want design decisions to go through a code-review

Graph

graph TD A[Client] --> B[Load Balancer] B --> C[Server01] B --> D[Server02]

Markdown

```mermaid
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
```

Sequence Diagram

Graph

sequenceDiagram Alice->>+John: Hello John, how are you? Alice->>+John: John, can you hear me? John-->>-Alice: Hi Alice, I can hear you! John-->>-Alice: I feel great!

Markdown

```mermaid
sequenceDiagram
Alice->>+John: Hello John, how are you?
Alice->>+John: John, can you hear me?
John-->>-Alice: Hi Alice, I can hear you!
John-->>-Alice: I feel great!
```

Gantt Diagram

Graph

gantt title A Gantt Diagram dateFormat YYYY-MM-DD section Section A task :a1, 2014-01-01, 30d Another task :after a1 , 20d section Another Task in sec :2014-01-12 , 12d another task : 24d

Markdown

```mermaid
gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2014-01-12  , 12d
    another task      : 24d
```

Mermaid Charts Docs

And back to where you were ↩

Last update: 2021-09-01