Markmap
markmap fence for an expandable mind map with zoom controls. Its source remains a readable Markdown outline.A markmap fence contains a Markdown outline. Headings and lists define the hierarchy.
The browser displays an expandable, collapsible tree. Use it to give an overview of a section.
For flows with direction or conditions, use Mermaid.
Shortest form
Enable Markmap in site configuration first. It is off by default. Without this setting, the fence stays a readable code block.
Then put the outline in a markmap fence:
# OINK
## Local-first
- every runtime ships with the theme
- no CDN involved
## Markdown-native
- components are fences and attribute lines
- usable without writing a shortcode
## Four output states
- HTML
- print
- Markdown
- RSS
The first-level heading is the root. Indentation places other headings and list items below it. Click a node’s dot to expand or collapse its branch. Scroll to zoom, and drag to pan. In OINK 1.4.0, Fit to window below the map restores the whole outline and resumes automatic fitting when the column changes width. Dragging or zooming suspends automatic fitting to preserve your reading position. The button also works with Tab and Enter.
Depth
Deeper levels use smaller text, and the canvas arranges itself. This example shows the theme documentation site’s six sections and their page counts.
# OINK documentation
## Introduction (4 pages)
### What it is
### Feature tour
### Showcase
### Licences
## Get started (4 pages)
### Choose a path
### OINK Starter
### Repository tour
### From scratch
## Authoring (8 pages)
### Organizing content
### Writing pages
### Front matter
### Blog
### Books
### Releases and downloads
### OpenAPI
## Components (22 pages)
### Callouts / tabs / steps / cards
### Images / galleries / tables / fields
### Diagrams: Mermaid / PlantUML / Markmap / ECharts
## Customization (15 pages)
### Branding / navigation / search / languages
### Landing / versions / taxonomies / print
## Operations (7 pages)
### Preview / deploy / upgrade
### Comments / analytics / troubleshooting
Links, code and emphasis
Nodes accept inline Markdown. Links are clickable, inline code is monospaced, and bold and italic text display normally.
# Everyday commands
## Preview
- `hugo server` — open [localhost:1313](http://localhost:1313/)
- `hugo server -D` — **including drafts**
## Build
- `hugo --printPathWarnings`
- `hugo --gc --minify` — for publishing
## Theme
- `hugo mod get -u github.com/pgsty/oink`
- [theme repository](https://github.com/pgsty/oink)
- [site source](https://github.com/pgsty/oink.pgsty.com)
Mathematics in nodes
The Markmap runtime includes local KaTeX. $…$ in nodes renders as a formula.
# PostgreSQL metrics worth watching
## Cache hit ratio
- $\frac{blks\_hit}{blks\_hit + blks\_read}$
- below 0.99, look at shared_buffers
## Replication lag
- $lsn_{primary} - lsn_{replica}$
## Transaction throughput
- $TPS = \frac{\Delta xact\_commit}{\Delta t}$
Controlling the initial depth
The fence body can start with Markmap’s YAML header. This is not Hugo front matter.
initialExpandLevel initially expands only the first levels. Readers can open the rest.
colorFreezeLevel sets the level from which a branch keeps one color.
---
markmap:
initialExpandLevel: 2
colorFreezeLevel: 2
---
# Check scripts in the theme repository
## Source-level contracts
### check-i18n.py
### check-taxonomy.py
### check-font-tokens.py
## Output-level checks
### check-output.py
### check-goldens.py
### check-code-blocks.py
### check-content-primitives.py
### check-media-primitives.py
## Browser runtimes
### node --test tests/js/**/*.test.js
Folded into a disclosure
Every map is 300 pixels tall. Three consecutive maps occupy considerable page space.
Put a large overview in > [!DETAILS] so readers can open it.
Start every disclosure line with >, including fence lines.
What the theme repository looks like
# pgsty/oink
## layouts/
- baseof.html and the per-type shells
- _partials/shell/
- _markup/ render hooks
- _shortcodes/
## assets/
- scss/ tokens and component styles
- js/ browser runtimes
- third_party/ libraries shipped with the theme
## i18n/
- 32 locale files with identical keys
## docs/
- maintainer contracts
Output
| Output | Shape |
|---|---|
| HTML | <pre><code class="language-markmap"> first; the runtime replaces it with <div class="markmap"> and draws the SVG |
| Same as HTML: the print view loads the runtime too | |
| Markdown | The markmap fence and its outline, kept as written |
| RSS | The outline source only — a readable outline for subscribers |
The outline supplies the content. Without JavaScript, the complete hierarchy remains readable.
Parameter reference
A markmap fence reads no attribute line. The theme fixes its height at 300px through .markmap > svg.
Its width fills the reading column.
Site parameters (hugo.yml):
Configuration defines the site key.
Put per-map behavior in the markmap: YAML header at the start of the body, such as initialExpandLevel, colorFreezeLevel, or maxWidth.
This is Markmap syntax. See the Markmap documentation for accepted keys.
Limits
- Inline SVG output is fixed at 300px tall by one
.markmap > svgrule. Fences cannot change this height. For many levels, useinitialExpandLevelor split the map.{#id num=}numbering and image zoom do not apply to inline SVG. - Node text follows the site’s text color; connecting lines retain Markmap’s own palette. Check custom colors in both modes.
- Without
params.markmap, the fence remains a code block. Sites that do not use Markmap load no runtime. - OINK 1.4.0 provides a fit control below each map; it is hidden in print.
- Avoid
<,>,&, and"in outlines. The current theme double-escapes them, displaying literal>or". Use[text](URL)links instead of angle-bracket autolinks.
Related
- Mermaid — diagrams with direction and conditions
- File trees — more precise for directory structure
- Callouts — everything
[!DETAILS]can do - Configuration —
params.markmap