Skip to content

Markdown & docs

Writing and formatting notes, and a short mkdocs how-to.

Headings and lists

Headings create document structure and anchor links:

# H1 — top-level (one per page)
## H2 — major section
### H3 — subsection

Unordered list (use - consistently over *):

- First item
- Second item
    - Nested item (four-space indent)

Ordered list (the actual numbers don't matter — markdown normalises them):

1. Step one
1. Step two
1. Step three

Task list (GitHub-flavoured Markdown):

- [x] Done
- [ ] Pending

Tables

Pipes and hyphens. The alignment colons are optional:

| Column A | Column B | Column C |
|----------|:--------:|---------:|
| left     | center   |    right |
| foo      | bar      |      baz |

Alignment: :-- left (default), :-: centre, --: right.

Fenced code blocks

Three backticks open and close the block; the language name after the opening fence enables syntax highlighting:

```python
def greet(name: str) -> str:
    return f"Hello, {name}!"
```

To show a fenced block inside a fenced block, use four backticks for the outer one.

Admonitions (mkdocs-material)

Coloured callout boxes:

!!! note "Optional title"
    Content indented four spaces.

!!! warning
    This will break things.

!!! tip
    Use `set -euo pipefail` in every script.

Types: note, tip, warning, danger, info, success, question, failure.

Collapsible variant (starts closed):

??? note "Click to expand"
    Hidden by default.

Inline link:

See the [Git workflows](git-workflows.md) page.

Reference-style (cleaner in prose-heavy pages):

Check the [Python docs][py] for details.

[py]: https://docs.python.org/3/

Link to a heading anchor (mkdocs auto-generates IDs):

[Jump to greedy vs lazy](#greedy-vs-lazy)

mkdocs how-to

Minimal project structure:

docs/
  index.md
  guide.md
mkdocs.yml

Install and serve locally with live-reload:

pip install mkdocs-material
mkdocs serve          # → http://127.0.0.1:8000

Build static HTML into site/:

mkdocs build -d site

Key mkdocs.yml settings:

site_name: My Notes
theme:
  name: material
  palette:
    - scheme: default
      primary: blue
  features:
    - navigation.top
    - search.suggest
    - content.code.copy
nav:
  - Home: index.md
  - Guide: guide.md

The nav: key controls page order and sidebar labels. Pages not listed in nav: still build but won't appear in the sidebar.

See also: Bash patterns for a deploy script that builds and rsyncs site/ to a server.