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 的写法：

片段	含义	示例
样式串	编号样式，_ 开头表示跳过一级，末尾符号为分隔符	1.1、A.a)、_1.I:
first-level N	从第 N 级标题开始编号	first-level 2
start-at N	首个编号层级起始值	start-at 3
max N	编号到第 N 级为止（1-6）	max 4
auto	（兼容写法）开启自动编号——当前版本默认全文档生效	auto
off	本文档停用（含豁免自动编号）	off

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

设置说明

设置项	说明
界面语言	中文 / English 切换
起始层级	从该级标题开始编号（默认 H2，跳过文档大标题）
结束层级	编号到该级为止，区间内连贯不断开（双滑条联动保证起始 ≤ 结束）
分隔符	. : - — ) 五种
起始编号	首个编号层级的起始值
自动编号延迟	编辑 / 打开文档后自动编号的防抖延迟（0.5 / 1 / 2 / 3 秒）
使用文档	GitHub 仓库链接

与社区插件 Number Headings 的差异

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

	Number Headings	本插件
自动编号	全局开关 + 10 秒轮询全文	编辑 / 打开事件驱动 + 可配置防抖延迟，默认全文档生效，单篇 off 豁免
层级范围	first-level + max 分开配置	起始 / 结束双滑条联动，区间连贯默认 H2-H6
单条解析失败	中断整批	跳过该条继续，不中断
提交方式	逐个替换	单事务批量提交，经济替换
界面	英文	中英双语可切换
兼容性	—	frontmatter 紧凑配置格式与其兼容，可直接迁移

技术说明

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

许可证

MIT License - Copyright (c) 2026 旭说