Section Numbering

Outline numbers for your headings — 1., 1.1., 1.2. — that stay right when you move sections around, without breaking the links that point at them. Show the numbers on screen and leave your notes untouched, or write them into the text; add a table of contents that keeps itself up to date.

## 1. Introduction
### 1.1. Scope
### 1.2. Terms
## 2. Method
### 2.1. Setup

Show numbers without changing the note

Turn on Show numbers without changing notes in the settings, or run Show or hide heading numbers, and every note gets its numbers drawn in front of its headings, in the editor and in reading view. The text stays ## Method; nothing is written, so there is nothing to renumber when you move a section, and no link can break. Add or move a heading and the numbers follow as you type.

The numbers follow the same settings as written ones, and a note's number headings property, ^skipped headings included. A note whose headings already have written numbers is left as it is, so a number never shows twice, and number headings: off turns them off for a note.

The core Outline sidebar shows the same numbers in front of each heading, so you see them where you navigate too, and they follow your edits there as well. Turn off Show numbers in the Outline to keep the Outline plain. Headings the plugin does not number, such as ^skipped ones or headings underlined with ===, appear in the Outline as they always did.

Shown numbers are not part of the text, so they are not in exports, copies or other apps. Copy this note with heading numbers puts the note on the clipboard with the numbers written in, for pasting elsewhere; the note itself is not changed. To keep the numbers in the file, use Number headings in this note instead.

Live table of contents

Insert live table of contents adds this block:

```section-contents
```

It is drawn as a list of links to the note's headings, numbered like the headings, and drawn again whenever they change: nothing to update by hand, and nothing written into the note but the block. Click an entry to go to the heading. Two options can go inside the block, one per line:

• depth: 2 lists only the first two numbered levels;
• numbers: off lists the headings without shown numbers.

Why links matter here

A link to a heading names the heading by its text: [[Guide#Setup]]. The moment a number is added, that heading is called 2.1. Setup, and every link to it quietly stops going anywhere. Renumber after moving a section and it happens again.

Section Numbering rewrites those links as part of the renumbering:

• wikilinks and embeds, [[Guide#Setup|alias]] and ![[Guide#Setup]], keeping the alias;
• Markdown links, [text](Guide.md#Setup), encoded or in angle brackets;
• nested heading paths, [[Guide#Method#Setup]];
• wikilinks inside properties;
• links within the note itself and, unless you switch it off, in every other note that links to it.

Links inside code, fenced or inline, are text about links and are left alone. Block references (#^id) are not headings and are never touched.

Commands

None has a hotkey by default; assign one in Settings → Hotkeys.

In the note you are editing, the headings and the links change in one edit, so a single undo puts everything back. Links in other notes are changed on disk, and undo in this note does not reach them — number again, or remove the numbers, to change them back.

Table of contents

Insert or update table of contents writes a Contents line carrying the block id ^toc, followed by a list of links to every heading in the numbered range, indented by level:

**Contents** ^toc
- [[#1. Introduction|1. Introduction]]
    - [[#1.1. Scope|1.1. Scope]]
- [[#2. Method|2. Method]]

From then on, numbering, renumbering or removing the numbers rewrites the list in the same edit, so its links never go stale. The list goes after whichever line ends with ^toc: rename the label, or make it a heading such as ## Contents ^toc, and it still works.

Settings

Text around the number

A template says what is written around the number, with {n} standing for it. Set Top-level template to Chapter {n}. and the other levels to {n}:

# Chapter 1. Guide
## 1.1. Intro
## 1.2. Method
# Chapter 2. Next

Text after {n} takes the place of the separator (Chapter {n}., 第{n}章, {n} —); a template that ends in {n} (Chapter {n}) keeps the separator. For lower levels {n} is the whole number, so Section {n} gives Section 1.2. With Chinese numerals, 第{n}章 gives 第一章 Guide.

The plugin reads the text it wrote, so numbering again never stacks a second Chapter 1. in front of the first, and Remove heading numbers takes the template text off as well. When you change a template, the next Number headings replaces the old text, because the plugin remembers the templates it has written. Shown numbers, the table of contents, Copy this note with heading numbers and the links to renumbered headings all use the text with the number. A note can set its own in its properties: number headings: template-level-1 "Chapter {n}.", template-level-other "{n}", 1.1. (A note that has the property but no template gets plain numbers.) Headings written by hand, such as ## Chapter two, are left as they are; only text that matches a template and a number is replaced. The default template {n} changes nothing.

Skipping headings

End a heading's line with the skip anchor and it is not numbered, takes no number, and stays out of the table of contents:

# Guide
## Preface ^skipped
## Setup

numbers as # 1. Guide, ## Preface ^skipped, ## 1.1. Setup. The anchor is a block id, so it needs a space before it. Numbering a heading that already had a number removes it once the anchor is there, and numbering again never puts one back; the anchor itself is never touched. Links to a skipped heading are left as they are.

As in Number Headings, a skipped heading is ignored altogether, as if the line were not a heading. Its subheadings are still numbered, and carry on from the nearest numbered heading above it, not from the skipped one. Mark each of them to leave a whole section unnumbered. A skipped heading never decides where numbering starts, so a skipped # Title above numbered ## sections does not make them 0.1, 0.2.

The anchor is ^skipped by default, the example Number Headings uses. Change it in the settings, or per note with skip ^name in the number headings property (skip none turns it off for the note).

Saving the settings to a note

Save numbering settings to this note's properties writes the plugin's settings as a number headings property, for example

number headings: first-level auto, max 6, skip ^skipped, start-at 1, 1.1.

An existing contents ^id part is kept; the rest is replaced. first-level auto is our own spelling for "the shallowest heading"; Number Headings ignores it. The property only applies while Follow Number Headings properties is on.

Why the default separator is a dot

To renumber, the plugin has to recognise a number it wrote earlier. With a separator that is unambiguous: ## 2024 in review has no dot after the year, so it becomes ## 1. 2024 in review and keeps its year. With no separator, a heading that starts with a number cannot be told apart from a numbered one, and the year would be replaced. Dotted numbers with no separator, such as 1.2 Scope, are recognised whatever the separator, but only in a note where every heading is numbered: in a note that is not, ## 2.0 migration is a version, not a number, and keeps it. A changelog whose every heading is a version, newest first, as in ## 2.0.1, ## 2.0.0, ## 1.9.0, keeps its versions too: numbers that go down, with three parts on a top-level heading, are not an outline.

Details

• A level that is skipped counts as zero, the way Pandoc numbers it: a ### straight under a # is 1.0.1..
• Headings inside frontmatter, code blocks and %% comments are not headings and are never numbered. Setext headings (text underlined with ===) are not numbered either.
• Empty headings are skipped and take no number.
• The table of contents leaves out the heading that carries its own anchor (## Contents ^toc) as well as skipped headings.
• When two headings share a name, a link to that name went to the first of them, and it still does after numbering.

Coming from Number Headings

Notes numbered by the original Number Headings plugin are picked up and renumbered in place. Its default writes top-level numbers with no separator (1 Introduction), so set Separator to none and your notes renumber exactly as they look now. To move to another separator, run Remove heading numbers in this note while it is still none, then change it and number again. While the separator is none, a heading that starts with a number, such as a year, is read as numbered.

Notes that carry Number Headings' own settings in their properties keep them. With Follow Number Headings properties on (the default), a note whose front matter says, for example,

number headings: auto, first-level 2, max 3, start-at 3, A.1

is numbered from heading 2 down to heading 3, starting at C, with numbers after the first written 1, 2, 3. The style may end in a separator (1.1., 1.1), 1.1:, 1.1 —, 1.1 -); without one there is none, as Number Headings writes it. _.1.1 starts numbering one level lower. number headings: off leaves the note alone. contents ^toc (any block id) says where the table of contents goes, as Number Headings reads it, so an existing one is kept up to date. skip ^id is honoured. auto is accepted and ignored. The styles also take a, i and 一 (lowercase letters, lowercase Roman and Chinese numerals), and template-level-1 / template-level-other set the text around the number; those are additions that Number Headings ignores.

Writing numbers into the text as you type is not included: rewriting links in other notes on every keystroke is not something a plugin should do behind your back. Shown numbers give you numbers that follow every edit without that.

Installing

From Obsidian: Settings → Community plugins → Browse, search for Section Numbering. Or copy main.js and manifest.json from the latest release into <vault>/.obsidian/plugins/section-numbering/.

Privacy

No network access, no telemetry. The plugin reads and writes only the notes that link to the one you are numbering.

Developing

npm install
npm test        # the numbering and link engine, under plain Node
npm run lint
npm run build

Everything under src/ is free of Obsidian imports and fully unit tested; main.ts is the only file that talks to the app.

More plugins by Siulved54

All of them are in the community directory: Settings -> Community plugins -> Browse, then search for the name.

License

MIT