Markdown Add Heading Numbers

Markdown Add Heading Numbers

What this tool does

This page adds hierarchical numbers to Markdown headings. It reads the heading levels in your document, then writes numbers such as 1, 1.1, 1.1.1 and so on. Existing numbers at the start of a heading are replaced, so you can renumber a draft without editing every line by hand. The conversion runs in your browser and produces a downloadable Markdown file. It is a numbering helper, not a full table-of-contents generator.

How the numbering works

A level-one heading starts a new top-level number. A level-two heading increases the second number and resets deeper levels. A level-three heading increases the third number, and so on through level six. If the document starts with a level-two heading, the tool still builds a sequence based on the headings it finds; it does not invent a missing parent heading. Read the output before you publish it.

How to use it

Paste your Markdown into the editor. Press Add Numbers. The output appears in a second editor, and a live count shows the input and output sizes. Use the copy button for the clipboard or download the result as markdown-heading-numbers.md. The Clear button resets both editors. There is no server request, so the document stays in the browser, but it still sits in the page until you clear it or close the tab.

Existing numbers are replaced

If a heading already begins with a number followed by a dot or a similar pattern, the tool replaces that prefix with the new hierarchy. That makes it easy to renumber after inserting a section. It also means a heading that legitimately starts with a number, such as '2026 Roadmap', can lose that number. Check the output for headings where the leading number is part of the title rather than a section number.

Code fences are skipped

Headings inside triple-backtick or triple-tilde fenced code blocks are not numbered. That is important for documentation that shows Markdown examples or shell comments beginning with a hash. The tool still has limits: Setext headings written with underlines, headings inside blockquotes, headings indented as code and hash lines without a space after the hash may be ignored. Review those cases manually.

Heading levels and hierarchy

The tool supports levels one through six. A jump from level one to level three produces a gap in the visible numbering, such as 1 then 1.1.1, unless the tool fills intermediate levels from the headings it sees. Markdown style guides often recommend not skipping levels. Numbering exposes that structure problem rather than hiding it, so use the output as a chance to fix the heading outline.

When numbering helps

Numbered headings make long documentation, policies, specifications and tutorials easier to reference. A reader can say 'see section 3.2' instead of describing a title. Numbers also make a table of contents easier to scan. For a short blog post or a page with only a few headings, numbering can add clutter. Use it when the document has a real hierarchy and readers need to cite parts of it.

What it does not do

The page does not build a linked table of contents. It does not add anchors, change heading text, reorder sections or validate that the outline is logical. It does not number list items or table rows. It does not understand Setext headings or every Markdown extension. It only changes the text at the start of recognized ATX headings.

Output and download

The output is plain Markdown with the numbers inserted. The download button saves a .md file. The copy button copies the output text. There is no server-side rendering, so the file is exactly the text you see. If you paste it into a system that uses a different Markdown flavor, preview it there; a heading that looks correct in one renderer can behave differently in another.

Large documents and browser limits

The tool runs entirely in the browser and does not state a hard input limit. Very large documents can still make the editor slow because the whole string is processed and displayed twice. Split a huge manual into chapters, number each chapter, then combine the results. Keep a backup of the original before replacing it.

Privacy and local processing

The Markdown is not sent to Newisty. It stays in the browser, which is convenient for internal notes and drafts. It is still visible to anyone with access to the device or the browser session. Clear the editors when you finish, especially on a shared computer. Copying the output puts it on the clipboard, where other applications may read it.

Common problems

If a heading was not numbered, check for a missing space after the hash, a Setext underline, a blockquote marker or indentation that turns it into code. If a title lost a leading year, restore it manually. If the numbering looks uneven, inspect the heading levels. If the page is slow, reduce the document size. If the download is empty, make sure the output editor contains text before downloading.

What not to do

Do not assume every Markdown heading style is recognized. Do not use the tool on a document where leading numbers are part of the titles without reviewing the result. Do not treat numbering as a substitute for a logical outline. Do not paste confidential material on a shared device. Do not overwrite the original until you have compared the output.

Numbering and anchor links

Changing a heading from an unnumbered title to a numbered one can change the anchor that a Markdown renderer generates. A link that pointed to the old heading may no longer resolve. If the document is already published, check internal links and any external links that target a heading. Some renderers keep a stable explicit ID; most generate the ID from the heading text. Renumbering is therefore a content change, not just a cosmetic one.

A worked example and the exact rules

Here is a short input with an old number, a skipped level and a fenced example:

# Overview
## 3.2 Setup
#### Requirements
## Usage
```md
# Not a real heading
```
# Reference

After pressing Add Numbers, the output is:

# 1 Overview
## 1.1 Setup
#### 1.1.1 Requirements
## 1.2 Usage
```md
# Not a real heading
```
# 2 Reference

The old 3.2 was removed and replaced. The level-four heading under a level-two heading received 1.1.1, not 1.1.0.1: the tool simply leaves out any level that has not been used yet, so skipped levels close up instead of showing a zero or a gap. The line inside the fence was left alone. The number is placed after the hash marks and a single space, followed by another space and the title, with no trailing dot.

Edge cases that change the result

• Prefix removal is strict. Only a leading run of digits and dots followed by a space is treated as an old number, such as 2, 2. or 2.4.1. A prefix like 1) or A. is kept, so you would get ## 1.1 1) Intro. A title such as 1.5x faster is safe because no space follows the number.
• The hash must start the line. A heading indented by even one space is not numbered, although many renderers still show it as a heading.
• Documents that start at level two. If the first headings are level two and a level-one heading appears later, both sequences can start at 1, giving duplicate numbers. Give the document a single top-level heading or keep all sections at the same starting level.
• Fences must close with the same character. A block opened with backticks only closes on a backtick fence, and a tilde block only on a tilde fence. A fence that is never closed makes the tool skip every heading below it.
• Closing hashes stay. In ## Title ##, the trailing hashes are kept as part of the text.
• Line endings. Windows line endings are converted to plain newlines in the output.

The counter under the input shows how many headings were detected, and the status panel shows how many were numbered. If the two do not match what you expect, look for indented headings or an unclosed fence before you copy the result.

Frequently Asked Questions