How to build a table of contents for your project readme
- Step 1Paste your README — Drop README.md into the upload box or paste its contents. The tool works on the raw Markdown source.
- Step 2Keep the title on top — Leave position at after-h1 so the TOC appears right below your
# Project Nameheading. - Step 3Scope to H2-H3 — Set minDepth=2 and maxDepth=3 for a clean section/sub-section list that skips the title and deep detail.
- Step 4Generate the TOC — Run it; the tool slugs each heading and assembles the nested bullet list under
## Table of Contents. - Step 5Verify the anchors — Spot-check a couple of links in the preview — section names with only letters, digits, and spaces resolve cleanly.
- Step 6Commit the README — Save and commit. Re-run whenever you add or rename a section to keep the TOC accurate.
Recommended settings for a README TOC
These are the only options the tool has. The values below give the standard GitHub-README look.
| Option | Set to | Why for a README |
|---|---|---|
| position | after-h1 (default) | Keeps # Project Name first; TOC appears directly beneath it. |
| minDepth | 2 | Excludes the H1 project title from the list — it is already the page heading. |
| maxDepth | 3 | Shows H2 sections and one level of H3 sub-sections; hides noisy H4+ detail. |
Common README headings and their anchors
Standard section names slug cleanly and match GitHub's rendered anchors.
| README heading | Anchor | Note |
|---|---|---|
| ## Installation | #installation | Single word, lowercased. |
| ## Getting Started | #getting-started | Space becomes a hyphen. |
| ## CI/CD Setup | #cicd-setup | The slash is stripped; cicd joins. |
| ## FAQ & Support | #faq-support | & removed; spaces collapse to one hyphen. |
| ## API (v2) | #api-v2 | Parentheses stripped, leaving a clean slug. |
What gets included vs. skipped
Only ATX headings in the depth range become entries; everything else is ignored.
| README element | In the TOC? | Reason |
|---|---|---|
## Usage heading | Yes | ATX heading within the depth range. |
| Badge image line | No | Not a heading line. |
# comment in a ```bash block | No | Inside a fenced code block — skipped. |
<h2> raw HTML heading | No | Only Markdown # headings are scanned. |
| H4 sub-detail with maxDepth=3 | No | Beyond the chosen maxDepth. |
Cookbook
Recipes tuned for open-source READMEs. Output is raw Markdown ready to commit straight into your repo.
Classic two-level README TOC (minDepth=2, maxDepth=3)
The standard look: sections and their immediate sub-sections, no title, no deep detail.
INPUT # Awesome CLI  ## Installation ## Usage ### Flags ### Examples ## Contributing #### Code of Conduct OUTPUT (TOC) ## Table of Contents - [Installation](#installation) - [Usage](#usage) - [Flags](#flags) - [Examples](#examples) - [Contributing](#contributing) # (badge line and H4 'Code of Conduct' are excluded)
TOC at the very top of the README
Some maintainers want navigation above the title and badges; use position=top.
INPUT # MyLib ## Features ## Install OUTPUT ## Table of Contents - [MyLib](#mylib) - [Features](#features) - [Install](#install) # MyLib ## Features ## Install
Slashes and ampersands in section names
Headings like CI/CD and FAQ & Support slug predictably — useful to verify before committing.
INPUT ## CI/CD Setup ## FAQ & Support OUTPUT (TOC) - [CI/CD Setup](#cicd-setup) - [FAQ & Support](#faq-support)
Refresh the TOC after renaming a section
Renaming Usage to Quickstart changes its anchor; re-run so the link does not break.
BEFORE rename - [Usage](#usage) AFTER renaming '## Usage' to '## Quickstart' and re-running - [Quickstart](#quickstart)
Badges and HTML stay; only headings are read
An HTML <h2> or a badge block is not a Markdown heading, so it is left alone and excluded from the TOC.
INPUT <h2 align="center">Logo</h2> # Project ## Docs OUTPUT (TOC excerpt) ## Table of Contents - [Docs](#docs) # the raw <h2> is not scanned
Edge cases and what actually happens
README starts with badges, then the H1
SupportedBadge lines are not headings, so they are skipped. With position=after-h1, the TOC still lands directly under the # Project heading.
Section title with emoji (`## 🚀 Quick Start`)
Emoji droppedThe emoji is stripped from the slug, giving #-quick-start after hyphen-trimming becomes #quick-start. The link text keeps the emoji, but verify the anchor — emoji handling differs from GitHub.
Centered HTML heading instead of Markdown
SkippedRaw <h1>/<h2> tags are not Markdown ATX headings, so they never appear in the TOC. Use # headings if you want them listed.
Two sections both named `## Examples`
Duplicate anchorBoth link to the first Examples section; the tool does not add -1/-2 suffixes like GitHub. Rename one (e.g. ## CLI Examples).
An old hand-written TOC already in the README
DuplicatedThe tool inserts a new TOC without removing the old one. Delete your previous TOC block first to avoid two stacked lists.
minDepth=2 on a README whose only heading is the H1
UnchangedIf every heading is filtered out by the depth range, no TOC qualifies and the README is returned untouched.
Heading wrapped in `**bold**` for emphasis
CleanedEmphasis markers are stripped before slugging, so ## **Beta** becomes - [Beta](#beta) — clean text and anchor.
Heading inside a fenced usage example
SkippedA # example line inside a ```bash block is treated as code, not a section, and is excluded from the TOC.
Closed ATX heading (`## Usage ##`)
Trailing hashes keptThe closing ## becomes part of the text and the anchor. Drop the trailing hashes for clean links.
Monorepo README over 1 MB on free tier
RejectedFiles past 1 MB / 500,000 characters are rejected on free. Pro raises the cap to 10 MB / 5,000,000 characters.
Frequently asked questions
Where does the TOC appear in my README?
With the default position=after-h1, immediately below your # Project Name title — right where contributors expect navigation. Use position=top to place it above the title.
Why is my H1 title showing up in the TOC?
minDepth defaults to 1, which includes the H1. Set minDepth=2 to exclude the title and start the list at your H2 sections.
Will the anchors work on GitHub?
For standard ASCII section names (Installation, Usage, Contributing) yes. Names with emoji or non-Latin characters can diverge because those characters are stripped.
Can I customize the 'Table of Contents' label?
Not in the tool — the heading is hard-coded as ## Table of Contents. Rename it in the output if you prefer ## Contents or similar.
Does it pick up badge images or HTML headings?
No. Only Markdown # headings are scanned. Badge lines and raw <h2> tags are ignored.
I renamed a section — do I need to regenerate?
Yes. Renaming a heading changes its anchor, so re-run the tool to keep the TOC links from breaking.
What about a TOC I already wrote by hand?
The tool adds a new one; it does not replace yours. Delete the old block first so you do not end up with two.
Two sections have the same name — why do both links go to one?
Identical text yields an identical slug, and the tool does not append -1/-2. Give the duplicate sections distinct names.
Is my repo content sent anywhere?
No. Everything runs in your browser; the README never leaves your machine.
How large a README can it handle?
Free tier: 1 MB / 500,000 characters — far more than any normal README. Pro and higher tiers handle much larger files.
Can I add a TOC to a CONTRIBUTING.md too?
Yes — it works on any Markdown file. Run it per file; for combining multiple docs first, see the Merger.
What if my README headings are at the wrong level?
Fix the hierarchy with the Heading Shifter, then generate the TOC. To sanity-check link targets, the Link Validator flags broken references.
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.