mirror of
https://github.com/jacobinwwey/obsidian-NotEMD.git
synced 2026-07-22 05:48:27 +00:00
docs: add chapter split toc showcase
This commit is contained in:
Jacobinwwey
parent
a6031c7367
commit
dd3a17e094
9 changed files with 228 additions and 1 deletions
|
|
@ -32,6 +32,14 @@ export default {
|
|||
{ text: 'Docs Hub (zh-CN)', link: '/README.zh-CN' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Feature Spotlights',
|
||||
collapsed: false,
|
||||
items: [
|
||||
{ text: 'Chapter Split + TOC (EN)', link: '/chapter-split-toc' },
|
||||
{ text: 'Chapter Split + TOC (zh-CN)', link: '/chapter-split-toc.zh-CN' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Releases',
|
||||
collapsed: false,
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@ This directory contains repository-level documentation for maintainers and contr
|
|||
## User And Maintainer Entry Points
|
||||
|
||||
- [Language Hub](./i18n/README.md)
|
||||
- [Chapter Split + TOC Extraction](./chapter-split-toc.md)
|
||||
- [Release Workflow](./maintainer/release-workflow.md)
|
||||
- [Release Notes 1.8.2](./releases/1.8.2.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -7,6 +7,7 @@
|
|||
## 用户与维护者入口
|
||||
|
||||
- [语言中心](./i18n/README_zh.md)
|
||||
- [章节拆分 + TOC 提取](./chapter-split-toc.zh-CN.md)
|
||||
- [发布流程](./maintainer/release-workflow.zh-CN.md)
|
||||
- [1.8.2 发布说明](./releases/1.8.2.zh-CN.md)
|
||||
|
||||
|
|
|
|||
80
docs/assets/chapter-split-toc-showcase.svg
Normal file
80
docs/assets/chapter-split-toc-showcase.svg
Normal file
|
|
@ -0,0 +1,80 @@
|
|||
<svg width="1600" height="960" viewBox="0 0 1600 960" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<linearGradient id="bg" x1="80" y1="40" x2="1520" y2="920" gradientUnits="userSpaceOnUse">
|
||||
<stop stop-color="#F6F1E8"/>
|
||||
<stop offset="0.5" stop-color="#E8F3F1"/>
|
||||
<stop offset="1" stop-color="#EEF2FF"/>
|
||||
</linearGradient>
|
||||
<linearGradient id="hero" x1="180" y1="132" x2="1420" y2="240" gradientUnits="userSpaceOnUse">
|
||||
<stop stop-color="#0F766E"/>
|
||||
<stop offset="1" stop-color="#1D4ED8"/>
|
||||
</linearGradient>
|
||||
<filter id="shadow" x="0" y="0" width="1600" height="960" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">
|
||||
<feDropShadow dx="0" dy="20" stdDeviation="20" flood-color="#0F172A" flood-opacity="0.12"/>
|
||||
</filter>
|
||||
</defs>
|
||||
|
||||
<rect width="1600" height="960" rx="36" fill="url(#bg)"/>
|
||||
|
||||
<rect x="96" y="84" width="1408" height="180" rx="32" fill="url(#hero)" filter="url(#shadow)"/>
|
||||
<text x="150" y="154" fill="#F8FAFC" font-size="26" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Notemd Feature Spotlight</text>
|
||||
<text x="150" y="216" fill="#FFFFFF" font-size="58" font-family="Segoe UI, Arial, sans-serif" font-weight="800">Chapter Split + TOC Extraction</text>
|
||||
<text x="150" y="250" fill="#DCEAFE" font-size="24" font-family="Segoe UI, Arial, sans-serif">Turn one long note into a linked chapter workspace beside the source file.</text>
|
||||
|
||||
<rect x="118" y="304" width="150" height="42" rx="21" fill="#CCFBF1"/>
|
||||
<text x="142" y="332" fill="#115E59" font-size="20" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Heading-aware</text>
|
||||
<rect x="280" y="304" width="122" height="42" rx="21" fill="#DBEAFE"/>
|
||||
<text x="309" y="332" fill="#1D4ED8" font-size="20" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Linked TOC</text>
|
||||
<rect x="414" y="304" width="142" height="42" rx="21" fill="#FEF3C7"/>
|
||||
<text x="445" y="332" fill="#B45309" font-size="20" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Safe reruns</text>
|
||||
<rect x="568" y="304" width="168" height="42" rx="21" fill="#EDE9FE"/>
|
||||
<text x="595" y="332" fill="#6D28D9" font-size="20" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Artifact cleanup</text>
|
||||
|
||||
<rect x="96" y="388" width="404" height="448" rx="30" fill="#FFFFFF" filter="url(#shadow)"/>
|
||||
<text x="132" y="444" fill="#0F172A" font-size="32" font-family="Segoe UI, Arial, sans-serif" font-weight="800">Source Note</text>
|
||||
<text x="132" y="478" fill="#475569" font-size="20" font-family="Segoe UI, Arial, sans-serif">One long Markdown note with nested headings</text>
|
||||
<rect x="132" y="516" width="332" height="280" rx="20" fill="#F8FAFC" stroke="#CBD5E1" stroke-width="2"/>
|
||||
<text x="158" y="566" fill="#111827" font-size="28" font-family="Consolas, Menlo, monospace" font-weight="700"># Platform</text>
|
||||
<text x="158" y="610" fill="#0F766E" font-size="26" font-family="Consolas, Menlo, monospace" font-weight="700">## Overview</text>
|
||||
<text x="190" y="648" fill="#334155" font-size="22" font-family="Consolas, Menlo, monospace">Overview body</text>
|
||||
<text x="158" y="694" fill="#1D4ED8" font-size="24" font-family="Consolas, Menlo, monospace" font-weight="700">### Scope</text>
|
||||
<text x="190" y="732" fill="#334155" font-size="22" font-family="Consolas, Menlo, monospace">Scope body</text>
|
||||
<text x="158" y="778" fill="#0F766E" font-size="26" font-family="Consolas, Menlo, monospace" font-weight="700">## Delivery</text>
|
||||
<text x="190" y="816" fill="#334155" font-size="22" font-family="Consolas, Menlo, monospace">Delivery body</text>
|
||||
|
||||
<path d="M534 612H626" stroke="#0F766E" stroke-width="10" stroke-linecap="round"/>
|
||||
<path d="M606 582L656 612L606 642" fill="none" stroke="#0F766E" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<text x="536" y="566" fill="#0F766E" font-size="22" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Run once</text>
|
||||
|
||||
<rect x="648" y="388" width="420" height="448" rx="30" fill="#FFFFFF" filter="url(#shadow)"/>
|
||||
<text x="684" y="444" fill="#0F172A" font-size="32" font-family="Segoe UI, Arial, sans-serif" font-weight="800">Generated TOC</text>
|
||||
<text x="684" y="478" fill="#475569" font-size="20" font-family="Segoe UI, Arial, sans-serif">Linked overview artifact with front-matter truth</text>
|
||||
<rect x="684" y="516" width="348" height="280" rx="20" fill="#F8FAFC" stroke="#CBD5E1" stroke-width="2"/>
|
||||
<text x="708" y="552" fill="#7C3AED" font-size="19" font-family="Consolas, Menlo, monospace">notemdArtifactKind: "chapter-split-toc"</text>
|
||||
<text x="708" y="582" fill="#334155" font-size="19" font-family="Consolas, Menlo, monospace">sourcePath: "Docs/Platform.md"</text>
|
||||
<text x="708" y="612" fill="#334155" font-size="19" font-family="Consolas, Menlo, monospace">resolvedSplitHeadingLevel: 2</text>
|
||||
<text x="708" y="642" fill="#334155" font-size="19" font-family="Consolas, Menlo, monospace">chapterCount: 2</text>
|
||||
<line x1="706" y1="666" x2="1010" y2="666" stroke="#CBD5E1" stroke-width="2"/>
|
||||
<text x="708" y="708" fill="#111827" font-size="24" font-family="Consolas, Menlo, monospace" font-weight="700">- [[01. Overview]]</text>
|
||||
<text x="736" y="744" fill="#1D4ED8" font-size="21" font-family="Consolas, Menlo, monospace">- [[#^notemd-scope|Scope]]</text>
|
||||
<text x="708" y="784" fill="#111827" font-size="24" font-family="Consolas, Menlo, monospace" font-weight="700">- [[02. Delivery]]</text>
|
||||
|
||||
<path d="M1104 612H1196" stroke="#1D4ED8" stroke-width="10" stroke-linecap="round"/>
|
||||
<path d="M1176 582L1226 612L1176 642" fill="none" stroke="#1D4ED8" stroke-width="10" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<text x="1092" y="566" fill="#1D4ED8" font-size="22" font-family="Segoe UI, Arial, sans-serif" font-weight="700">Managed artifacts</text>
|
||||
|
||||
<rect x="1216" y="388" width="288" height="448" rx="30" fill="#FFFFFF" filter="url(#shadow)"/>
|
||||
<text x="1252" y="444" fill="#0F172A" font-size="32" font-family="Segoe UI, Arial, sans-serif" font-weight="800">Output Folder</text>
|
||||
<text x="1252" y="478" fill="#475569" font-size="20" font-family="Segoe UI, Arial, sans-serif">Everything lands beside the source note</text>
|
||||
<rect x="1252" y="516" width="216" height="280" rx="20" fill="#F8FAFC" stroke="#CBD5E1" stroke-width="2"/>
|
||||
<text x="1274" y="560" fill="#0F172A" font-size="24" font-family="Consolas, Menlo, monospace" font-weight="700">Platform_chapters/</text>
|
||||
<text x="1288" y="604" fill="#7C3AED" font-size="20" font-family="Consolas, Menlo, monospace">├─ Platform_TOC.md</text>
|
||||
<text x="1288" y="644" fill="#0F766E" font-size="20" font-family="Consolas, Menlo, monospace">├─ 01-overview.md</text>
|
||||
<text x="1288" y="684" fill="#0F766E" font-size="20" font-family="Consolas, Menlo, monospace">├─ 02-delivery.md</text>
|
||||
<text x="1288" y="724" fill="#64748B" font-size="20" font-family="Consolas, Menlo, monospace">└─ .notemd-chapter-split.json</text>
|
||||
<rect x="1270" y="748" width="180" height="30" rx="15" fill="#E0F2FE"/>
|
||||
<text x="1294" y="769" fill="#0369A1" font-size="17" font-family="Segoe UI, Arial, sans-serif" font-weight="700">stale files cleaned on rerun</text>
|
||||
|
||||
<rect x="96" y="866" width="1408" height="48" rx="24" fill="#0F172A"/>
|
||||
<text x="126" y="897" fill="#E2E8F0" font-size="22" font-family="Segoe UI, Arial, sans-serif">Deterministic TOC metadata • Stable nested-heading block refs • Manual-edit protection • Explicit split-level control</text>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 7.3 KiB |
|
|
@ -38,7 +38,7 @@ canonical: true
|
|||
| B. CLI / automation surface | 当前主线现已具备 registry-backed 的 config/profile export/import、脱敏 provider 导出、public-surface 导出、已进入 registry-backed typed contract 的 `content.split-note-by-chapters`，以及覆盖有界 path-based 操作与 export 操作的 repo-local maintainer help/invoke 脚本，其中也包含 maintainer-only 的 `local-knowledge.inspect` retrieval introspection | 备份分支还承载过更宽的 maintainer-bridge 设想，但当前 reintegration 刻意保持在窄边界内 | 继续把 maintainer helper 的边界写清楚；若任何 path-based operation 要提升为更广或更公共的 CLI 面，必须同批补齐契约/测试/文档；不要让最近 provider/settings 进展模糊这条分层边界 | 不要把当前能力面写成通用 public CLI，或无边界的 maintainer mutation API | P1 |
|
||||
| C. 用户可见 settings / preview / onboarding | 当前主线现已具备 preview flows、preview history、欢迎弹窗 release digest、provider diagnostics、settings reset、concept-note 前置配置提示、API liveness/activity UI、面向已保存工件的 preview 恢复链路，并已重新同步 `1.9.0` 的 release-facing version truth | 备份分支还有更多 UX 收口尝试，但目前已恢复切片已在当前主线上重新证明 | 继续保持 sidebar / preview / settings 的文案、i18n、已保存工件行为与 release-facing version truth 一致 | 不要再把这些 UX guardrail 写成“当前主线缺失”，但也不要顺手高估尚未恢复的 UX 想法 | P1 |
|
||||
| D. Regex / 文件筛选 / local-KB / chapter split | 当前主线现已具备 file-selection profiles、文件夹 regex/glob 筛选、`relativePath` / `basename` 匹配、可选子目录范围控制、覆盖 `从标题生成`、`从标题批量生成`、`研究与总结`、`生成图形` 的 local-KB retrieval、混合的 Vault 相对文件/文件夹知识库路径、带默认回退语义的按任务知识库覆盖列表、chapter split、面向重复标题的稳定 TOC block ref、确定性的 TOC front-matter metadata、manifest-backed 的 guarded rerun overwrite 语义、对应回归测试、面向标题生成/研究总结/artifact-mode 图形结果路径的 machine-readable retrieval 摘要与 timing/size telemetry、用于检查 effective path/query/context 的 maintainer-only retrieval inspect seam、支持临时 `knowledgePaths` override 数组做 ad hoc task-scoped retrieval 检查，以及通过 `npm run verify:local-kb-fixtures` 暴露、且已覆盖 mixed file/folder task-scoped inspect case 的更宽离线夹具 | 备份分支提供了最初恢复证据；当前主线现在已直接携带该有界产品切片与后续 Stage C 收口结果 | 下一步应转向 mixed-note/query corpus 覆盖扩充、maintainer example 对齐与评估深度收口，而不是继续证明这些能力“是否存在” | 不要继续把这些能力写成只存在于 backup、或 live mainline 尚未具备；不要把 single-title / task-scoped retrieval 契约从文档里漏掉；也不要在文档或契约里把 retrieval 再压回 boolean-only signaling | P1 |
|
||||
| E. Provider settings / model discovery | 当前主线现已具备 metadata-driven 的 provider settings panel：其背后由 `src/llmProviders.ts` 提供共享字段 taxonomy，支持显式的 core/contextual/advanced/developer 分组、基于持久化 override 的 advanced auto-expand，以及面向一批已验证 OpenAI-compatible `/models` 预设（含 LM Studio、Groq、Fireworks、多项中国区 provider、`New API`、`OVMS`）、OpenRouter 有界 chat + embedding catalog 聚合、LiteLLM 显式 proxy-family `/models` + `/model/info` 聚合、Together 专用 `/models` 响应、Anthropic `GET /models`、Ollama tags、Google Gemini model listing、Huawei Cloud MaaS 专用 `v2/models`、Vercel AI Gateway 有界 `/v1/models` + `v3/ai/config` 双源合并、`AIHubMix` 托管 `/api/v1/models` registry、`GitHub Models` 的 `catalog/models` + `/v1/models` 双源发现、PPIO 的 chat + embedding + reranker 三路有界发现、OVMS 优先 `/v3/models` 并有界回退 `/v1/config` 的本地发现，以及 xAI 的 `/v1/language-models`；Google `nextPageToken` 与 Anthropic `has_more` / `last_id` 这类分页 registry 现在也会做有界多页遍历；runtime 与 discovery 还已收敛到共享的 OpenAI-compatible header owner 与 endpoint normalization，以避免 `Authorization` / `X-Api-Key` / provider-specific compatibility header` 语义继续漂移，并容忍 `/responses`、`/chat/completions`、`/models` 这类 endpoint 形态；generic `OpenAI Compatible` 还会把 OVMS 风格本地 `/v3` 端点与 LiteLLM 风格本地 proxy 分开路由；同时仍保持手动 `model` 字符串作为持久化 source-of-truth，共享 parser 现已兼容 object-shaped proxy catalog、nested `specification.modelId`、wrapped `provider_models` / `publisherModels` / `registry` / `services` 目录，以及 `models/<id>`、`publishers/<owner>/models/<id>` 这类 resource-style 名称归一化，并已补齐对 gateway/provider-prefixed 模型的有界 token-cap guidance；此外，当 generic `OpenAI Compatible` 的 base URL 指向 OpenAI、DashScope/Qwen、Xiaomi MiMo、Fireworks、Hugging Face 这类已知 trusted official host 时，bare model ID 现在也会复用官方 provider 的 token-cap 元数据 | 这里没有值得“恢复”的 backup-branch 已发货实现；这条能力来自 current-main 代码、`.trellis/tasks/05-27-provider-settings-model-discovery/` 下的 Cherry Studio 对照研究，以及已经验证完成并合回的隔离实现通道 | 把这条轨道降为 bounded breadth-maintenance：继续通过共享 family/response-shape 语义扩宽支持，而不是退回 provider-name 分支；只有在 endpoint 语义、header owner、fallback 行为、token metadata 与测试/文档都足够稳定时，才扩到更多 provider family | 不要把当前有界 helper 误写成已经具备完整 Cherry Studio parity、持久化远程 model catalog、或所有 provider 都支持模型发现；generic `OpenAI Compatible` 的 bare model token ceiling 也只能在已知 trusted host 上写成当前主线真值，不能扩写成对任意 custom gateway 都成立 | P1/P2 |
|
||||
| E. Provider settings / model discovery | 当前主线现已具备 metadata-driven 的 provider settings panel：其背后由 `src/llmProviders.ts` 提供共享字段 taxonomy，支持显式的 core/contextual/advanced/developer 分组、基于持久化 override 的 advanced auto-expand，以及面向一批已验证 OpenAI-compatible `/models` 预设（含 LM Studio、Groq、Fireworks、多项中国区 provider、`New API`、`OVMS`）、OpenRouter 有界 chat + embedding catalog 聚合、LiteLLM 显式 proxy-family `/models` + `/model/info` 聚合、Together 专用 `/models` 响应、Anthropic `GET /models`、Ollama tags、Google Gemini model listing、Huawei Cloud MaaS 专用 `v2/models`、Vercel AI Gateway 有界 `/v1/models` + `v3/ai/config` 双源合并、`AIHubMix` 托管 `/api/v1/models` registry、`GitHub Models` 的 `catalog/models` + `/v1/models` 双源发现、PPIO 的 chat + embedding + reranker 三路有界发现、OVMS 优先 `/v3/models` 并有界回退 `/v1/config` 的本地发现，以及 xAI 的 `/v1/language-models`；Google `nextPageToken` 与 Anthropic `has_more` / `last_id` 这类分页 registry 现在也会做有界多页遍历；runtime 与 discovery 还已收敛到共享的 OpenAI-compatible header owner 与 endpoint normalization，以避免 `Authorization` / `X-Api-Key` / `provider-specific compatibility header` 语义继续漂移，并容忍 `/responses`、`/chat/completions`、`/models` 这类 endpoint 形态；generic `OpenAI Compatible` 还会把 OVMS 风格本地 `/v3` 端点与 LiteLLM 风格本地 proxy 分开路由；同时仍保持手动 `model` 字符串作为持久化 source-of-truth，共享 parser 现已兼容 object-shaped proxy catalog、nested `specification.modelId`、wrapped `provider_models` / `publisherModels` / `registry` / `services` 目录，以及 `models/<id>`、`publishers/<owner>/models/<id>` 这类 resource-style 名称归一化，并已补齐对 gateway/provider-prefixed 模型的有界 token-cap guidance；此外，当 generic `OpenAI Compatible` 的 base URL 指向 OpenAI、DashScope/Qwen、Xiaomi MiMo、Fireworks、Hugging Face 这类已知 trusted official host 时，bare model ID 现在也会复用官方 provider 的 token-cap 元数据 | 这里没有值得“恢复”的 backup-branch 已发货实现；这条能力来自 current-main 代码、`.trellis/tasks/05-27-provider-settings-model-discovery/` 下的 Cherry Studio 对照研究，以及已经验证完成并合回的隔离实现通道 | 把这条轨道降为 bounded breadth-maintenance：继续通过共享 family/response-shape 语义扩宽支持，而不是退回 provider-name 分支；只有在 endpoint 语义、header owner、fallback 行为、token metadata 与测试/文档都足够稳定时，才扩到更多 provider family | 不要把当前有界 helper 误写成已经具备完整 Cherry Studio parity、持久化远程 model catalog、或所有 provider 都支持模型发现；generic `OpenAI Compatible` 的 bare model token ceiling 也只能在已知 trusted host 上写成当前主线真值，不能扩写成对任意 custom gateway 都成立 | P1/P2 |
|
||||
| F. Release / repo-saga / clean-state hygiene | 当前主线现已具备 release/repo-saga 脚本，以及 repo-saga 执行锁、测试、文档与本地工件忽略 guardrail；在最新 provider 轨道收口后，当前分支也已重新回到 clean 状态 | 备份分支推动了这些 guardrail；当前主线已恢复有界串行安全切片 | 保持 repo-saga 刷新流程的串行纪律，并把 clean-state 证明作为持续满足的收尾不变量，而不是重新积累成“以后再清理”的债务 | 不要把“脚本还在”误读为“可以并行跑 repo-saga 刷新路径”，也不要再回到“先做完再说，工作区之后再清”的收尾漂移 | P0 |
|
||||
|
||||
## 4. 当前主线已确认 register
|
||||
|
|
|
|||
70
docs/chapter-split-toc.md
Normal file
70
docs/chapter-split-toc.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
# Chapter Split + TOC Extraction
|
||||
|
||||
|
||||
|
||||
Turn one long note into a managed chapter workspace beside the source file.
|
||||
|
||||
Notemd's `Chapter Split + TOC Extraction` flow is designed for notes that have already grown past the point where one flat Markdown file is still pleasant to navigate. Instead of asking you to manually duplicate headings, create chapter files, and wire a hand-written table of contents, Notemd generates a linked TOC artifact, chapter notes, and managed metadata in one pass.
|
||||
|
||||
## What You Get
|
||||
|
||||
- Heading-aware chapter note generation beside the source note
|
||||
- A linked TOC artifact with deterministic front-matter metadata
|
||||
- Stable nested-heading block references such as `#^notemd-scope`
|
||||
- Manifest-backed rerun safety and stale generated-file cleanup
|
||||
- Explicit split-level control: `Auto` or force `H1`-`H6`
|
||||
|
||||
## Real Output Shape
|
||||
|
||||
```text
|
||||
Docs/Platform.md
|
||||
└─ Docs/Platform_chapters/
|
||||
├─ Platform_TOC.md
|
||||
├─ 01-overview.md
|
||||
├─ 02-delivery.md
|
||||
└─ .notemd-chapter-split.json
|
||||
```
|
||||
|
||||
## Example TOC Excerpt
|
||||
|
||||
```md
|
||||
---
|
||||
notemdGenerated: true
|
||||
notemdArtifactKind: "chapter-split-toc"
|
||||
sourcePath: "Docs/Platform.md"
|
||||
requestedSplitHeadingLevel: "auto"
|
||||
resolvedSplitHeadingLevel: 2
|
||||
chapterCount: 2
|
||||
---
|
||||
|
||||
# Platform TOC
|
||||
|
||||
- [[Docs/Platform_chapters/01-overview|01. Overview]]
|
||||
- [[Docs/Platform_chapters/01-overview#^notemd-scope|Scope]]
|
||||
- [[Docs/Platform_chapters/02-delivery|02. Delivery]]
|
||||
```
|
||||
|
||||
## Why This Feature Is Useful
|
||||
|
||||
- It converts a large note into a navigable chapter set without losing the original source context.
|
||||
- It keeps the TOC as a first-class artifact instead of a disposable copy-paste summary.
|
||||
- It stays safe on reruns: generated artifacts are tracked, stale artifacts can be removed, and manually edited generated notes are protected from blind overwrite.
|
||||
|
||||
## Best-Fit Scenarios
|
||||
|
||||
- Research notes that started as one file and need chapter-level navigation
|
||||
- Long project plans that should keep an overview note plus per-section notes
|
||||
- Reading notes or technical roadmaps where nested sections need deep links
|
||||
- Knowledge-base curation where a TOC should remain shareable and explicit
|
||||
|
||||
## What Makes Notemd's Approach Different
|
||||
|
||||
- It does not stop at "split headings into files."
|
||||
- It keeps TOC generation, artifact tracking, block-ref stability, and rerun cleanup in the same managed flow.
|
||||
- It is explicit about failure: if you force `H3` and the note has no `H3`, the operation fails instead of silently guessing.
|
||||
|
||||
## Related Feature Surface
|
||||
|
||||
- Command / sidebar entry: `Chapter Split`
|
||||
- Output truth: `<basename>_chapters`, `<basename>_TOC.md`, `.notemd-chapter-split.json`
|
||||
- Setting: `Chapter Split -> Split heading level`
|
||||
63
docs/chapter-split-toc.zh-CN.md
Normal file
63
docs/chapter-split-toc.zh-CN.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
# 章节拆分 + TOC 提取
|
||||
|
||||
|
||||
|
||||
当一篇笔记已经长到不适合继续在单文件里维护时，这个功能会在原文件旁生成章节文件、TOC 和一份 manifest。
|
||||
|
||||
它按标题结构拆分内容，保留章节之间的链接关系，也给重复执行留出了边界。你不需要手工复制标题，也不用自己维护目录文件。
|
||||
|
||||
## 输出结构
|
||||
|
||||
执行后会生成下面这组文件：
|
||||
|
||||
```text
|
||||
Docs/Platform.md
|
||||
└─ Docs/Platform_chapters/
|
||||
├─ Platform_TOC.md
|
||||
├─ 01-overview.md
|
||||
├─ 02-delivery.md
|
||||
└─ .notemd-chapter-split.json
|
||||
```
|
||||
|
||||
## TOC 示例片段
|
||||
|
||||
```md
|
||||
---
|
||||
notemdGenerated: true
|
||||
notemdArtifactKind: "chapter-split-toc"
|
||||
sourcePath: "Docs/Platform.md"
|
||||
requestedSplitHeadingLevel: "auto"
|
||||
resolvedSplitHeadingLevel: 2
|
||||
chapterCount: 2
|
||||
---
|
||||
|
||||
# Platform TOC
|
||||
|
||||
- [[Docs/Platform_chapters/01-overview|01. Overview]]
|
||||
- [[Docs/Platform_chapters/01-overview#^notemd-scope|Scope]]
|
||||
- [[Docs/Platform_chapters/02-delivery|02. Delivery]]
|
||||
```
|
||||
|
||||
这里有几个实现上的关键点：
|
||||
|
||||
- TOC 带 front matter，能明确标识源文件、拆分层级和章节数量。
|
||||
- 子标题链接会写稳定 block ref，例如 `#^notemd-scope`，便于在 TOC 里直接深链。
|
||||
- 生成产物会记录到 `.notemd-chapter-split.json`，再次执行时可以识别旧文件并做清理。
|
||||
|
||||
## 适合什么时候用
|
||||
|
||||
- 研究笔记已经很长，单文件内查找开始变慢。
|
||||
- 项目计划需要保留总览，同时把每一章拆成独立文件。
|
||||
- 你需要一份可引用的 TOC，而不是临时整理一次就丢掉。
|
||||
|
||||
## 行为边界
|
||||
|
||||
- 拆分层级可以选 `Auto`，也可以强制指定 `H1` 到 `H6`。
|
||||
- 如果你强制指定了某个层级，但源文档里没有这个层级，任务会直接报错，不会自动猜。
|
||||
- 再次执行时会清理陈旧产物；如果某个已生成文件被手工改过，系统不会直接覆盖。
|
||||
|
||||
## 入口与设置
|
||||
|
||||
- 命令 / sidebar 入口：`章节拆分`
|
||||
- 输出真值：`<basename>_chapters`、`<basename>_TOC.md`、`.notemd-chapter-split.json`
|
||||
- 设置项：`章节拆分 -> 拆分标题层级`
|
||||
|
|
@ -6,6 +6,8 @@ Repository docs preview for `obsidian-NotEMD`.
|
|||
|
||||
- [Docs Hub (EN)](./README.md)
|
||||
- [Docs Hub (zh-CN)](./README.zh-CN.md)
|
||||
- [Chapter Split + TOC (EN)](./chapter-split-toc.md)
|
||||
- [Chapter Split + TOC (zh-CN)](./chapter-split-toc.zh-CN.md)
|
||||
- [Release Notes 1.8.2 (EN)](./releases/1.8.2.md)
|
||||
- [Release Notes 1.8.2 (zh-CN)](./releases/1.8.2.zh-CN.md)
|
||||
|
||||
|
|
|
|||
|
|
@ -6,6 +6,8 @@
|
|||
|
||||
- [文档中心（英文）](./README.md)
|
||||
- [文档中心（中文）](./README.zh-CN.md)
|
||||
- [章节拆分 + TOC（英文）](./chapter-split-toc.md)
|
||||
- [章节拆分 + TOC（中文）](./chapter-split-toc.zh-CN.md)
|
||||
- [1.8.2 发布说明（英文）](./releases/1.8.2.md)
|
||||
- [1.8.2 发布说明（中文）](./releases/1.8.2.zh-CN.md)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue