Section Numbering

by siulved54
5
4
3
2
1
Score: 51/100

Description

Reviews

No reviews yet.

Stats

0
stars
3,413
downloads
0
forks
56
days
1
days
1
days
41
total PRs
1
open PRs
0
closed PRs
40
merged PRs
1
total issues
1
open issues
0
closed issues
54
commits

Latest Version

2 days ago

Changelog

  • Keep numbers up to date as you write. An opt-in setting renumbers a note that already has written numbers when typing pauses, with its table of contents and the links within the note, in one edit that one undo takes back; the caret stays where you are. Links in other notes follow in one batch when you leave the note or after a longer pause. number headings: auto (as Number Headings writes it) now turns this on for a note, even with the setting off. Notes that are off, numbered by another plugin, or shown without changing the note are never touched.

README file from

Github

Section Numbering

Latest release CI License: MIT

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.

**Interface languages:** English, 简体中文, 日本語, 한국어, Español, Deutsch, Français, Português (Brasil) and Русский, following Obsidian's language setting. A translation that reads wrong? [Open an issue](https://github.com/perezamadorluisenrique-gif/section-numbering/issues/new/choose) with the text and what it should say.

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

Running Number headings in this note: the headings get numbers, and links to them in the same note and in another note are rewritten

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.

Live Preview with shown numbers: the headings read 1. Guide, 1.1. Introduction, 1.2. Method and so on, and a live table of contents above them lists the same numbers

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.

Keep numbers up to date as you write

Turn on Keep numbers up to date as you write (off by default) and a note that already has written numbers is renumbered when you stop typing for a moment, about a second and a half. Add ## Background between two numbered sections, pause, and it reads ## 2. Background, the sections after it move on by one, and the ^toc table of contents and the links within the note follow, all in one edit. Your caret and selection stay on the text they were on, moved along by the characters put in front of them.

  • Undo: one Ctrl+Z (Cmd+Z) removes the automatic renumbering and leaves what you typed. Nothing is renumbered again until you type in the note.
  • Links in other notes are not rewritten on every pause. They are updated in one go when you leave the note, or after about ten seconds without an edit, with a notice saying how many changed (switch it off with Update links in other notes). Until then a link from another note to a heading whose number just changed points at the old number.
  • Which notes: the setting never adds numbers to a note that has none; run Number headings in this note once to start. A note whose number headings property includes auto, as Number Headings writes it (number headings: auto, 1.1.), is kept up to date even when the setting is off, and is numbered the first time you edit it. A folder rule whose value includes auto does the same for its notes; a note's own property wins over its folder's rule.
  • Never touched: notes with number headings: off or in a folder whose rule is off, notes another plugin numbers (numbering profile, such as Section Numbering Pro), and notes whose numbers are shown without changing the note: shown numbers already follow every edit, so nothing is written there.
  • A pass waits while an input method is composing text, and while the caret is inside a number it would rewrite.

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.

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.

Before and after numbering: the Guide note on the left, and on the right a note whose links to Guide headings were rewritten to the numbered names

Commands

Command What it does
Number headings in this note Numbers every heading in range, or renumbers it if it is already numbered.
Remove heading numbers in this note Takes the numbers off again.
Insert or update table of contents Inserts a list of links to the headings at the cursor, or brings the existing one up to date.
Show or hide heading numbers (without changing notes) Turns the shown numbers on or off.
Insert live table of contents Adds a table of contents block that keeps itself up to date.
Copy this note with heading numbers Copies the note with the numbers written in, leaving the note as it is.
Save numbering settings to this note's properties Writes the plugin's current settings into the note's number headings property, so the note keeps numbering this way whatever the settings become.
Add a numbering rule for this note's folder Gives the note's folder a rule that holds the plugin's current settings, and opens the folder rules to edit it.

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

Setting Default
Show numbers without changing notes Off Draws the numbers in front of headings without writing them. See Show numbers without changing the note.
Show numbers in the Outline On While numbers are shown without changing notes, the Outline sidebar shows them too. It has no effect otherwise.
Keep numbers up to date as you write Off Renumbers a note that already has written numbers when typing pauses. See Keep numbers up to date as you write.
First numbered level Automatic The level that gets a single number. Automatic uses the shallowest heading in each note. Shallower headings stay unnumbered and restart the count, so with level 2 each # chapter numbers its sections from 1.
Last numbered level Heading 6 Deeper headings are left as they are.
Top-level numbers 1, 2, 3 Or A, B, C; a, b, c; I, II, III; i, ii, iii; or Chinese numerals 一, 二, 三 (十, 十一, 二十一, 一百 ...).
Lower-level numbers 1, 2, 3 The same choice for every level below.
Separator 1.2. Heading Also ), :, —, - or none.
Top-level template {n} Text around the number of top-level headings. See Text around the number.
Lower-level template {n} The same for every level below.
Skip anchor ^skipped A heading whose line ends with this block id is left unnumbered. See Skipping headings. Empty turns it off.
Follow Number Headings properties On A note's number headings property overrides the settings above for that note. See Coming from Number Headings.
Update links in other notes On Links within the note are always updated.

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.

Folder rules

A folder can have numbering of its own. Settings → Section Numbering → Folder rules lists the rules; each one is a folder, a value, and whether numbers are drawn on screen for it. The value is written exactly like a note's number headings property, so you can copy one to the other:

Folder Value Show numbers
Papers A.1. as set
Papers/Drafts off as set
Manual template-level-1 "Chapter {n}." on

The deepest folder that holds a note wins, a note's own number headings property wins over any rule, and the rule wins over the plugin's settings. A rule that is off leaves its notes alone unless a note has a property of its own. Leave the value empty to change only whether numbers are drawn. A rule follows its folder when you rename or move it, and moving a note to another folder numbers it by that folder's rule. Rules need no network access and change no note by themselves.

Notes another plugin numbers

A note whose properties hold numbering profile: something is numbered by another plugin, so every numbering command and the shown numbers leave its headings alone, and the command says why in a notice. numbering profile: off means no profile: the note is numbered as usual.

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 keeps the note numbered as you write, as in Number Headings (see Keep numbers up to date as you write). 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.

Numbers written as you type are opt-in: links in other notes follow in one batch when you leave the note, never on every keystroke. Shown numbers give you numbers that follow every edit without writing anything.

Pro

Section Numbering Pro is an optional paid companion (one-time payment, 14-day free trial) for documents that span several notes: numbering profiles, cross-references between notes that follow renumbering, figure and table numbers, and export to HTML, Pandoc and LaTeX. Everything described above stays free in this plugin.

Free template

templates/report-starter is a numbered report skeleton with a live table of contents. To turn notes into a book, see the free starter in Book Studio.

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.

For developers

Another plugin can take over the notes it numbers itself, and hear when a note is renumbered, through a small versioned API. It needs no setting and makes no network request. The types are in src/api.ts, which imports nothing, so you can copy it.

import type { App, Events } from 'obsidian';
// Copy the types from src/api.ts.

function sectionNumbering(app: App): SectionNumberingApiV1 | null {
  const plugins = (app as unknown as { plugins?: { getPlugin?(id: string): unknown } }).plugins;
  const api = (plugins?.getPlugin?.('section-numbering') as { api?: { apiVersion?: unknown } } | null | undefined)?.api;
  return api && api.apiVersion === 1 ? (api as SectionNumberingApiV1) : null;
}

// In onload: register now if it is there, and again whenever Section Numbering (re)loads.
const attach = (api: SectionNumberingApiV1 | null) => {
  if (api) this.register(api.claimNotes('my-plugin', (note) => (isMine(note) ? { owner: 'My Plugin' } : null)));
};
attach(sectionNumbering(this.app));
this.registerEvent((this.app.workspace as Events).on('section-numbering:api-ready', (api) => attach(api as SectionNumberingApiV1)));
  • claimNotes(id, handler) returns a disposer. A note you claim is left alone by every Section Numbering command, by its shown numbers and by its Outline, so only one plugin writes numbers into it. The handler runs synchronously, often (on every keystroke while numbers are shown): keep it cheap and do not write from it. The first handler that claims a note wins.
  • on('renumbered', listener) runs after a numbering or removal command changed a note and Section Numbering rewrote links to it in other notes, and after each batch of links that follows automatic renumbering (kind numbered, with the renames since the last batch). The payload has the note's path, its new text (the editor's, which may not be on disk yet), kind, renames, changed and linksUpdated. Do not rewrite those links again. on('settings-changed', listener) runs after the settings or the folder rules changed. Listeners are not awaited, and a failing one affects nobody else.
  • redraw() draws the shown numbers, live contents blocks and the Outline again: call it after your claims change.
  • Reloading Section Numbering drops every claim and listener; register again on section-numbering:api-ready.
  • apiVersion only goes up on a breaking change. Optional members, events and payload fields can be added to version 1, so check for them before use. A later version would be offered beside this one for at least a release.

More plugins by Siulved54

Plugin What it does Source
Shared Blocks Write a block of text once and reuse it in any note. Edit the source and every reference re-renders live. shared-blocks
Text Case and Cleanup Change case, make camelCase or slugs, sort lines and remove duplicates, and repair text pasted out of a PDF, without touching code or URLs. text-format
Typography as You Type Curly quotes, dashes and ellipses as you type, kept out of code and maths, with Backspace to take one back. smart-typography-plugin
Spreadsheet to Table Paste cells from Excel or Google Sheets as a Markdown table with a real header, insert CSV files, and copy tables back out. spreadsheet-to-table
Hybrid Line Numbers Relative and hybrid line numbers for Vim-style jumps, where a folded section counts as one line. hybrid-line-numbers
List Item Callouts Colour a single list item as a callout by starting it with a character such as &, ! or ?. list-item-callouts
Folder Counts See how many notes or files each folder holds, right in the file explorer, with a vault total and folder exclusions. folder-counts
Note Reading Time Reading time of the current note or your selection in the status bar, optionally saved to a property. note-reading-time
Task Rollover Roll unfinished tasks from your last daily note into today's when it is created, with a real undo. task-rollover
Zoom Into Section Zoom into a heading or list item to see only it and its contents, with a breadcrumb bar to climb back out. zoom-into-section
Link Title on Paste Paste a web address and get a Markdown link with the page's title, fetched in the background and undone in one step. link-title-on-paste
Update Radar Checks your installed community plugins for updates in the background, shows what changed, and flags the ones that look abandoned. community-update-checker
Dataview to Bases Convert Dataview queries into Bases blocks, and see which queries in your vault can be converted. dataview-to-bases
Line Editing Commands Duplicate, join, sort and reverse lines, insert blank lines and jump to a line number, with multi-cursor support. line-editing-commands
Note Mover Rules Move notes into folders by ordered rules on tags, properties, titles and paths, with a preview before any bulk move. note-mover-rules
Tab History Keeps each tab's back and forward history across restarts, and adds commands to move, maximize and close tabs. tab-history
URL Cards Shows web addresses as cards with title, description and image, and reads existing cardlink blocks. url-cards
Vim Config Loads a vimrc-style file from your vault so your key mappings and editor commands are ready when vim mode starts. vim-config
Task Archive Moves completed tasks, with their sub-items, into an archive section or note. task-archive
Revisit Later Link the current note into a future daily note, with a date typed in plain English, so it comes back when you want to review it. revisit-later
Explorer Colors Plus Color files and folders in the file explorer, with a palette, cascading to children, and import from File Color. explorer-colors-plus
Book Lookup Create book notes from Open Library or Google Books, with cover images, ISBN search and Book Search compatible templates. book-lookup
Web Search Menu Search the web for selected text or the note title from the right-click menu, with engines you define. web-search-menu
Word Lookup Look up any word in a sidebar dictionary with definitions, phonetics, synonyms and antonyms, or create a note for it. word-lookup
Quick Translate Translate the selection or a whole note into another language with no account, keeping links, code and front matter untouched. quick-translate
Dice Rolls Inline dice rolls you click to reroll, in Live Preview and Reading view, with full dice notation, a roll dialog and a roll history. Reads Dice Roller notes. dice-rolls
Claude Studio Notion-style AI writing, chat and vault tools powered by your local Claude Code CLI. claude-studio
Book Studio Turn notes into a print-ready paperback PDF and an EPUB 3, entirely on your device. book-studio
Emoji Search Insert emojis from a searchable picker or by typing a :shortcode. emoji-search
Inline TOC Show a live table of contents inside any note with a toc code block, or insert a plain Markdown one. inline-toc

All of them are in the community directory: Settings -> Community plugins -> Browse, then search for the name. Demos and install links for every one: the catalog.

Pro and templates

Optional paid extras, one-time payment. Everything in the free plugins stays free.

Follow new plugins and updates on X: @luenpereza

License

MIT