XU Number Headings

[!NOTE] 中文说明 标题编号：为 Markdown 标题生成多级数字编号（1.1.1），层级区间连贯可选（默认 H2-H6），frontmatter 按文档覆盖全局设置，可自动重新编号。

为 Markdown 标题生成多级数字编号（如 1.1.1），起始层级与结束层级双滑条联动（区间内连贯不断开，默认 H2-H6 跳过文档大标题），可自定义起始值与分隔符。编辑或打开文档后自动重新编号（延迟可配置），单篇文档可在 frontmatter 写 off 豁免，或用一行紧凑配置覆盖全局设置。

English description below for review purposes. / 以下为英文说明，用于过审。

Generate hierarchical numbers for Markdown headings (e.g. 1.1.1) with a contiguous, slider-configurable heading level range (H1-H6, default H2-H6), custom start value and separator. Documents renumber automatically on edit or open with a configurable delay; a per-document off in frontmatter opts out, and one compact frontmatter line can override global settings.

功能特性

• 连贯层级区间：起始 / 结束层级双滑条联动（H1-H6，默认 H2-H6），区间内层级连贯不断开，跳过文档大标题
• 数字多级编号：编号栈算法生成 1.1.1 式编号，同级递增、升级压层、降级弹层；兼容旧 frontmatter 的字母 / 罗马样式解析
• frontmatter 覆盖：文档 frontmatter 一行 number headings: 1.1 即可按文档覆盖全局设置，优先级最高，off 一键停用
• 自动编号：编辑或打开文档后按可配置延迟（0.5-3 秒）自动重新编号，默认全文档生效（事件驱动无轮询，frontmatter 写 off 可对单篇豁免）
• 单事务提交：所有修改一次事务写入，文本无变化不产生变更（不污染撤销栈），重跑先剥离旧编号
• 编号移除：一键清除所有编号前缀，保留标题原文

Features

• Contiguous level range: start / end level dual sliders linked (H1-H6, default H2-H6, skipping the document title)
• Multi-level numeric numbering via a numbering stack; legacy frontmatter letter / Roman styles still parsed for compatibility
• Frontmatter override: one line like number headings: 1.1 overrides global settings per document; off disables
• Auto renumbering: documents renumber after a configurable delay (0.5-3s) on edit or open, enabled for all documents by default (event-driven, no polling; a per-file off in frontmatter opts out)
• Single transaction commit; unchanged text produces no changes (undo-stack friendly); re-running strips old numbers first
• Remove all numbering with one command

安装

方式一：从 Obsidian 社区目录安装（推荐）

1. 打开 Obsidian 设置 → 社区插件
2. 点击「浏览」，搜索 "XU Number Headings"
3. 点击「安装」，然后「启用」

方式二：手动安装

1. 从 最新 Release 下载 main.js、manifest.json、styles.css 三个文件
2. 在 vault 中创建目录 .obsidian/plugins/xu-number-headings/
3. 将三个文件放入该目录
4. 打开 Obsidian 设置 → 社区插件，找到 XU Number Headings 并开启

Installation

From Obsidian Community Directory:

1. Open Obsidian Settings → Community Plugins
2. Click "Browse" and search for "XU Number Headings"
3. Click "Install", then "Enable"

Manual Installation:

1. Download main.js, manifest.json, styles.css from the latest release
2. Put them in <vault>/.obsidian/plugins/xu-number-headings/
3. Enable in Settings → Community Plugins

使用方法

编号

1. 打开目标文档，Ctrl+P 打开命令面板，搜索「编号所有标题」
2. 执行后按当前设置（或文档 frontmatter 覆盖）为层级区间内的标题生成编号；重复执行会先剥离旧编号再生成新编号
3. 需要时可先在设置中调整层级区间，或绑定快捷键

移除编号

1. Ctrl+P 搜索「移除所有编号」并执行
2. 所有匹配当前样式的编号前缀被清除，标题文字保留

保存设置到 frontmatter

1. 调整好全局设置后，Ctrl+P 搜索「保存设置到 frontmatter」
2. 当前设置以紧凑格式写入本文档 frontmatter，此后本文档使用自己的配置：

---
number headings: first-level 2, max 4, 1.1)
---

自动编号

默认对所有文档生效：编辑或打开文档后，按设置的延迟自动重新编号（事件驱动，无轮询）。不想自动编号的文档在 frontmatter 写 off 豁免：

---
number headings: off
---

frontmatter 配置格式

逗号分隔的紧凑串，兼容社区插件 Number Headings 的写法：

Usage

1. Open the target document, press Ctrl+P and run "Number all headings"; headings within the configured level range are numbered, re-running strips old numbers first
2. "Remove numbering" clears all number prefixes matching the current style
3. "Save settings to frontmatter" writes the current settings as one compact frontmatter line for this document
4. All documents renumber automatically after the configured delay on edit or open; add number headings: off to a document's frontmatter to opt out

设置说明

命令列表

与社区插件 Number Headings 的差异

本插件参考 number-headings-obsidian 的核心算法重写，主要差异：

技术说明

• 纯 JavaScript 实现（main.js），无需编译，直接可用
• main.ts 为 TypeScript 源码参考，供二次开发使用
• 编号核心纯函数实现，无第三方依赖，可独立单元测试
• 兼容移动端（isDesktopOnly: false）

已知限制

• 旧编号剥离采用宽松匹配以兼容多种历史编号格式：若标题文字本身以「数字 / 字母 + 分隔符（. : 等）+ 空格」开头（如 12: 30 的会议、2.0 升级指南），执行「编号所有标题」或「移除所有编号」时该前缀可能被误识别为旧编号而剥除。此类文档可在 frontmatter 写 number headings: off 豁免。

Known Limitations

• Old-prefix stripping uses lenient matching for compatibility with historical numbering formats: if a heading's text itself starts with "number / letter + separator (. : etc.) + space" (e.g. 12: 30 的会议 or 2.0 Release Notes), running "Number all headings" or "Remove numbering" may misread that prefix as an old number and strip it. Add number headings: off to the document's frontmatter to opt out.

许可证

MIT License - Copyright (c) 2026 旭说