How to add a table of contents to technical handbooks
- Step 1Load the handbook — Paste the runbook or upload the .md file. Works on the raw Markdown source, command blocks and all.
- Step 2Keep the title first — Leave position at after-h1 so the TOC lands under the handbook title where responders expect it.
- Step 3Scope to procedure level — Set minDepth=2 and maxDepth=3 to list systems (H2) and procedures (H3) without H4 implementation noise.
- Step 4Generate the TOC — Run it; each heading is slugged and linked, with command-block lines automatically excluded.
- Step 5Verify critical links — Click through to the failover, rollback, and escalation sections to confirm anchors resolve.
- Step 6Commit to the repo — Save and commit. Add 'regenerate TOC' to your runbook-review checklist so it never drifts.
Recommended settings for runbooks
The full option set; these values give the standard ops-handbook layout.
| Option | Set to | Why for a runbook |
|---|---|---|
| position | after-h1 (default) | TOC sits under the handbook title — the first thing responders see. |
| minDepth | 2 | Excludes the H1 title; lists systems/sections starting at H2. |
| maxDepth | 3 | Includes H3 procedures but hides H4 implementation notes to keep the index scannable. |
Typical runbook headings and anchors
Operational section names slug cleanly and match GitHub's rendered anchors.
| Runbook heading | Anchor | Note |
|---|---|---|
| ## Database Failover | #database-failover | Spaces hyphenated; standard slug. |
| ### Step 1: Drain Traffic | #step-1-drain-traffic | Colon stripped; digits and words kept. |
| ## Rollback / Recovery | #rollback-recovery | Slash stripped; the run of hyphens from the surrounding spaces collapses to one. |
| ## On-Call Escalation | #on-call-escalation | Existing hyphen preserved; clean slug. |
| ### P0 Incident Response | #p0-incident-response | Alphanumerics kept; spaces hyphenated. |
What is indexed vs. ignored in a runbook
Only ATX headings in range become entries; commands and metadata are left alone.
| Handbook element | In the TOC? | Reason |
|---|---|---|
## Incident Response heading | Yes | ATX heading within the depth range. |
# stop the service in a ```bash block | No | Inside a fenced code block — skipped. |
Frontmatter owner: field | No | Frontmatter is preserved, not parsed for headings. |
| H4 'Implementation Notes' with maxDepth=3 | No | Beyond the chosen maxDepth. |
<h2> HTML heading | No | Only Markdown # headings are scanned. |
Cookbook
Recipes for on-call handbooks, runbooks, and ops manuals. Output is plain Markdown ready to commit to your ops repo.
Procedure-level TOC for a runbook (minDepth=2, maxDepth=3)
List systems and their procedures; hide deep implementation notes.
INPUT # Payments Runbook ## Database Failover ### Drain Traffic #### Internal: connection pools ## Rollback OUTPUT (TOC) ## Table of Contents - [Database Failover](#database-failover) - [Drain Traffic](#drain-traffic) - [Rollback](#rollback) # H4 'Internal: connection pools' is excluded; H1 title excluded by minDepth=2
Numbered steps keep their numbers
Procedure steps with numbers and colons slug predictably for stable anchors.
INPUT ### Step 1: Verify Replica Lag ### Step 2: Promote Replica OUTPUT (TOC) - [Step 1: Verify Replica Lag](#step-1-verify-replica-lag) - [Step 2: Promote Replica](#step-2-promote-replica)
Command blocks do not leak into the TOC
A comment line in a shell snippet looks like a heading but is correctly skipped.
INPUT ## Restart Service ```bash # stop the worker first systemctl stop worker ``` ## Verify OUTPUT (TOC) - [Restart Service](#restart-service) - [Verify](#verify) # the '# stop the worker first' comment is ignored
Handbook metadata is preserved
Front-matter owner/rotation/review fields stay intact; the TOC goes below them.
INPUT --- owner: payments-team last_reviewed: 2026-06-01 --- # Payments Runbook ## Escalation OUTPUT --- owner: payments-team last_reviewed: 2026-06-01 --- # Payments Runbook ## Table of Contents - [Escalation](#escalation) ## Escalation
Slash in a section name
Rollback / Recovery slugs with the slash removed — verify before linking from incident docs.
INPUT ## Rollback / Recovery OUTPUT (TOC) - [Rollback / Recovery](#rollback-recovery) # the slash is stripped and the run of hyphens collapses to a single one
Edge cases and what actually happens
Comment line inside a command block
SkippedA # stop the service comment inside a fenced ```bash block is treated as code, not a heading, so it never becomes a phantom TOC entry.
Section name with a slash (Rollback / Recovery)
By designThe slash is stripped and the resulting run of hyphens collapses to a single one, giving #rollback-recovery. Note GitHub keeps a double hyphen here, so this anchor can differ from GitHub for slash-separated titles.
Numbered steps with colons
Supported### Step 1: Drain slugs to #step-1-drain — the colon is stripped, digits and words kept. Stable anchors for procedures you link from incident tickets.
Handbook split across many files
Per fileThe tool processes one file at a time. Run it on each handbook file, or combine first with the Merger and generate one master TOC.
Sensitive credentials in the handbook
PreservedThe tool only reads headings and inserts a TOC; it does not redact secrets. Run the Secret Redactor separately if the doc contains keys or tokens before sharing.
Two procedures with the same name across systems
Duplicate anchorBoth 'Rollback' headings share one slug and link to the first. No -1/-2 is added — qualify them (e.g. 'DB Rollback', 'App Rollback') for distinct links.
An old TOC already at the top of the runbook
DuplicatedThe tool inserts a fresh TOC without deleting the old one. Remove the previous block first to avoid a stacked, confusing index.
Handbook starts at H2 (no H1 title)
Falls backWith position=after-h1 and no H1, the TOC is placed at the top of the body. Add a # Handbook title if you want it above the TOC.
minDepth=2 on a handbook that uses only H1 sections
UnchangedIf every heading is filtered out by the depth range, no TOC is added and the file is returned as-is. Lower minDepth to 1 to include H1 sections.
Large consolidated handbook over 1 MB on free
RejectedFiles past 1 MB / 500,000 characters are rejected on free. A big consolidated ops manual may need Pro (10 MB / 5,000,000 characters).
Frequently asked questions
Where will the TOC appear in my runbook?
By default, immediately under the H1 title (position=after-h1) — the first place an on-call engineer looks. Use position=top to put it above the title.
How do I keep the index scannable for a deep handbook?
Set minDepth=2 and maxDepth=3 so it lists systems (H2) and procedures (H3) but hides H4 implementation detail.
Will command samples mess up the TOC?
No. Lines inside fenced `` code blocks are skipped, so a # comment` in a shell snippet never becomes a TOC entry.
Does it keep my handbook frontmatter (owner, rotation)?
Yes. YAML and TOML frontmatter are detected and preserved; the TOC is inserted below the metadata block.
Are the anchors GitHub-compatible for repo-hosted runbooks?
For the plain-text section names runbooks use, yes. Non-Latin characters are stripped, which differs from GitHub, but operational headings are normally ASCII.
My handbook is split across several files — what do I do?
Run the tool on each file (it handles one at a time), or combine them first with the Merger and generate a single master TOC.
Does it redact secrets in the handbook?
No — it only inserts a TOC. If the doc contains keys or tokens, run the Secret Redactor before sharing.
Two systems both have a 'Rollback' section — why one link?
Identical text yields the same slug and the tool does not append -1/-2. Qualify the headings (e.g. 'DB Rollback') for unique anchors.
Is the handbook uploaded anywhere?
No. Processing runs entirely in your browser, so sensitive internal docs never leave your machine.
How often should I regenerate the TOC?
After any heading change. Add 'regenerate TOC' to your runbook-review checklist so the index never drifts from the content.
How large a handbook can it process?
Free tier: 1 MB / 500,000 characters. Pro: 10 MB / 5,000,000. A big consolidated manual may need Pro.
What if the heading levels in my runbook are inconsistent?
Normalize them with the Heading Shifter first, then generate the TOC so the structure is accurate. The Frontmatter Builder helps standardize owner/review metadata.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.