Markdown Examples

A cheatsheet of everything you can use to make pages on this site prettier. Each section shows the source first, then how it renders.

Companion to Contribution Guidelines — write your page there, style it from here.

Callouts

The callouts plugin lets you use GitHub / Obsidian style callouts. Easiest way to make a page look good.

> [!NOTE]
> Useful information a reader should notice.

> [!TIP]
> A helpful shortcut.

> [!WARNING]
> Something that can bite you.

Renders as:

Note

Useful information a reader should notice.

Tip

A helpful shortcut.

Warning

Something that can bite you.

All the types

Info

[!INFO] — general context.

Success

[!SUCCESS] — it worked. Also [!CHECK], [!DONE].

Question

[!QUESTION] — FAQ style. Also [!HELP], [!FAQ].

Failure

[!FAILURE] — the thing that does not work. Also [!FAIL], [!MISSING].

Danger

[!DANGER] — destructive or unsafe. Also [!ERROR].

Bug

[!BUG] — known issue.

Example

[!EXAMPLE] — sample usage.

Quote

[!QUOTE] — a citation.

Abstract

[!ABSTRACT] — summary / TL;DR.

Custom titles

> [!TIP] Run it locally first
> Always `mkdocs serve` before opening a PR.

Run it locally first

Always mkdocs serve before opening a PR.

Collapsible callouts

Add + to start open, - to start closed.

> [!NOTE]- Click me to expand
> Hidden until the reader wants it. Great for long output logs.

Click me to expand

Hidden until the reader wants it. Great for long output logs.

Starts expanded

Use + when the content matters but you still want it boxed off.

Admonitions (the other syntax)

Callouts compile down to these. Both work — use whichever you prefer, but stay consistent within a page.

!!! note "Optional custom title"
    Indented four spaces.

??? warning "Collapsed by default"
    Same thing, but foldable.

???+ info "Expanded by default"
    Starts open.

Optional custom title

Indented four spaces.

Collapsed by default

Same thing, but foldable.

Expanded by default

Starts open.

Code blocks

Plain fenced block with a language:

```bash
mkdocs serve
```

With a title

```yaml title="mkdocs.yml"
site_name: WDCC Docs
```

mkdocs.yml

site_name: WDCC Docs

With line numbers and highlighted lines

```ts title="src/server.ts" linenums="1" hl_lines="2 5"
const app = express();
app.use(cors());          // highlighted

app.get("/health", (_, res) => {
  res.json({ ok: true }); // highlighted
});
```

src/server.ts
const app = express();
app.use(cors());          // highlighted

app.get("/health", (_, res) => {
  res.json({ ok: true }); // highlighted
});

Inline code

Wrap in single backticks: pnpm install. For a shell command a reader must run, inline code beats a full block.

Tables

| Environment | URL                    | Deploys from |
| ----------- | ---------------------- | ------------ |
| Production  | `wdcc.co.nz`           | `main`       |
| Preview     | `*.fly.dev`            | any PR       |

Environment	URL	Deploys from
Production	`wdcc.co.nz`	`main`
Preview	`*.fly.dev`	any PR

Align columns with : in the separator row: :--- left, :---: centre, ---: right.

Links

Goal	Syntax
External	`[WDCC](https://wdcc.co.nz)`
Another page	`[Contributing](contributing.md)`
Page in a folder	`[Fly](tech/guides/deployment-fly.md)`
Up a folder	`[Home](../index.md)`
Heading same page	`[Tables](#tables)`
Heading elsewhere	`[Setup](contributing.md#local-setup)`

Link to .md files, not .html — MkDocs rewrites them, and mkdocs build --strict will catch it if the target moves.

Heading anchors are the heading lowercased with spaces turned into - and punctuation dropped: ## Local setup becomes #local-setup.

Note

External links on this site open in a new tab automatically (docs/scripts/new-tab-links.js). You do not need to do anything.

Images

![Alt text describing the image](assets/screenshot.png)

Store files under docs/assets/ and use a relative path. Always write real alt text — it shows if the image fails to load.

Lists

- Bullet
- Another
  - Nested (two spaces)

1. Numbered
2. Second
   1. Nested

Term
:   Definition style is not enabled, use a table instead.

Quotes and rules

> A plain blockquote, for actual quotations.
> Use a callout instead if you mean "pay attention".

---

A plain blockquote, for actual quotations.

Not enabled yet

These need a line added to markdown_extensions: in mkdocs.yml. Ask in the tech channel before adding — extra syntax is only worth it if pages use it.

Feature	Extension
`{#custom-anchor}` and `{ .class }` on elements	`attr_list`
Content tabs (`=== "npm"` / `=== "pnpm"`)	`pymdownx.tabbed`
Task lists (`- [x] done`)	`pymdownx.tasklist`
Emoji / icons (`:material-rocket:`)	`pymdownx.emoji`
Keyboard keys (`++ctrl+c++`)	`pymdownx.keys`
Highlight, strikethrough, sub/superscript	`pymdownx.caret`, `pymdownx.mark`, `pymdownx.tilde`
Footnotes	`footnotes`
`¶` permalink on every heading	`toc: permalink: true`

Checklist before you commit

[ ] mkdocs serve --livereload and eyeball the page
[ ] mkdocs build --strict passes (catches broken links)
[ ] Page added to nav: in mkdocs.yml, or it will not appear in the sidebar

Warning

Task list checkboxes above render as literal [ ] until pymdownx.tasklist is enabled — a live example of the table right above.