Markdown Heading Numberer

Add automatic section numbers to Markdown headings — turn a document of #, ##, and ### headings into a cleanly numbered outline like 1, 1.1, 1.2, 2. Choose which heading level starts the numbering, the separator between levels, and whether each number ends in a dot. Headings inside fenced code blocks are left untouched. Everything runs live in your browser.

How to use the Markdown Heading Numberer

Paste your Markdown on the left and the numbered version appears on the right, updating as you type. Use Start at to choose which heading level becomes section "1": leave it on ## if your document uses a single # as the title and you want the chapters beneath it numbered, or pick # to number from the very top. The Separator is the character placed between levels — a dot gives 1.2.3, but you can use a dash or any short string. Tick Trailing separator to end each number with the separator too, producing the 1. and 1.2. style common in manuals.

Numbering follows the heading hierarchy: each time a deeper level appears its counter starts again, and returning to a shallower level continues where it left off, so an ## after a run of ### headings increments the top number and resets the sub-counter. Any existing leading number on a heading is removed first, so you can re-run the tool after editing without the numbers piling up. Headings inside fenced code blocks (between ``` or ~~~) are ignored, since a # there is usually a comment, not a heading.

Use the Copy button to grab the result. Everything runs in your browser, so it is instant, works offline, and nothing you paste is uploaded anywhere.

Why number Markdown headings

Markdown deliberately has no built-in concept of section numbers. A heading is just a line beginning with one to six hash marks, and the rendered HTML — <h1> through <h6> — carries a level but no automatic "1.2.3" prefix. For a blog post that is fine, but for documentation, specifications, theses, contracts, and internal handbooks, numbered sections are expected. They let people refer to "section 3.2" in a review, a ticket, or a conversation; they make a long document navigable; and they signal structure at a glance. The usual fix is to type the numbers by hand, which is tedious and, worse, fragile: insert one section near the top and every number below it is suddenly wrong.

Automatic numbering solves that by deriving the labels from the heading structure itself. The rule is simple and is exactly what this tool applies. Walk the document top to bottom keeping a counter for each level. When you meet a heading, increment the counter for its level, reset the counters for every deeper level to zero, and write out the chain of counters from the top level down to this one, joined by your chosen separator. So three second-level headings under the first chapter become 1.1, 1.2, 1.3; the next first-level heading rolls over to 2 and its first child restarts at 2.1. Because the numbers are computed rather than typed, reordering or inserting sections and re-running the tool always yields a consistent sequence.

Two choices make the output match different conventions. The first is where numbering begins. Many Markdown documents reserve a single top-level # for the document title and place real content under ## headings; in that layout you want the ## headings to be 1, 2, 3 and the title left alone, which is why this tool lets you start at any level and leaves shallower headings unnumbered. The second is the trailing separator. Technical books and legal documents often write 1. and 1.2. with a final dot, while web style guides tend to drop it. Neither is more correct, so the option is yours. One thing the tool does not do is renumber inside code blocks — a line like # install dependencies in a shell snippet is a comment, and treating it as a heading would corrupt the example. By respecting fences, numbering stays where it belongs: on the prose structure a reader actually navigates.

Common use cases

  • Documentation. Give a manual or README numbered sections people can cite precisely.
  • Specifications and RFCs. Produce the 1, 1.1, 1.2 numbering these documents conventionally use.
  • Theses and reports. Number chapters and subsections without maintaining them by hand.
  • Editing. Reorder sections freely, then re-run to get a correct, gap-free sequence.

Frequently asked questions

Does it change my heading text?
No. It only adds a number after the hash marks and before your text. Any existing leading number is stripped first so re-running does not stack numbers, but the words of the heading are untouched.

Why are some headings left unnumbered?
Headings above the level you chose in "Start at" are skipped. If you start at H2, a single H1 title stays as-is and the H2 headings become 1, 2, 3. Headings inside code fences are also skipped.

Can I use a separator other than a dot?
Yes. Type any short string in the separator box — a dash gives 1-2-3, for example. The trailing-separator option then appends that same character to the end of each number.

How does it handle skipped levels?
It numbers by the actual hash count of each heading. If you jump from H2 straight to H4, the H4 is treated as the next level down; keeping your heading levels consecutive gives the cleanest numbering.