feat: change default heading-depth from 3 to 4

CoderJackZhu · claude · CoderJackZhu · commit 3346dc4d36fc · 2026-05-15T17:54:09.000+08:00
Allows one more level of heading hierarchy by default, better matching
typical document structures without resorting to list items too early.

Co-Authored-By: Claude Opus 4.7 &lt;noreply@anthropic.com&gt;
diff --git a/README-en.md b/README-en.md
@@ -46,7 +46,7 @@ MindCtx works with standard Markdown. Headings become tree branches, lists becom
 ```markdown
 ---
 mindctx: true
-heading-depth: 3
+heading-depth: 4
 ---
 
 # Project Plan
@@ -63,7 +63,7 @@ heading-depth: 3
 - Testing
 ```
 
-The `heading-depth` setting (default 3) controls when headings become list items. See [format spec](docs/format-spec.md) for details.
+The `heading-depth` setting (default 4) controls when headings become list items. See [format spec](docs/format-spec.md) for details.
 
 ## Keyboard Shortcuts
 
diff --git a/README.md b/README.md
@@ -58,7 +58,7 @@ MindCtx 使用标准 Markdown。标题成为树的分支，列表成为叶节点
 ```markdown
 ---
 mindctx: true
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 项目规划
@@ -75,7 +75,7 @@ heading-depth: 3
 - 测试验证
 ```
 
-`heading-depth`（默认 3）控制标题转列表的分界线。详见 [格式规范](docs/format-spec.md)。
+`heading-depth`（默认 4）控制标题转列表的分界线。详见 [格式规范](docs/format-spec.md)。
 
 ## 快捷键
 
diff --git a/docs/format-spec.md b/docs/format-spec.md
@@ -15,15 +15,15 @@ MindCtx 使用标准 Markdown 作为数据格式。本文档定义 `.mind.md` 
 ---
 mindctx: true
 default-view: outline
-heading-depth: 3
+heading-depth: 4
 ---
 ```
 
 | 字段 | 类型 | 默认值 | 说明 |
 |------|------|--------|------|
 | `mindctx` | boolean | — | 标记文件为 MindCtx 文档（非 `.mind.md` 文件必填） |
 | `default-view` | string | `"outline"` | 默认打开的视图，可选 `"outline"` 或 `"mindmap"` |
-| `heading-depth` | integer | `3` | 标题最大深度（1–6），超过此深度的节点序列化为列表项 |
+| `heading-depth` | integer | `4` | 标题最大深度（1–6），超过此深度的节点序列化为列表项 |
 
 ## 树结构映射
 
@@ -207,7 +207,7 @@ ID = fnv1a64("祖先标题1/祖先标题2/当前标题:兄弟索引")
 ---
 mindctx: true
 default-view: outline
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 产品需求文档：在线协作白板
diff --git a/docs/功能指南.md b/docs/功能指南.md
@@ -159,7 +159,7 @@ maxDepth: 4
 
 ### 导入注意事项
 
-- 导入时 `heading-depth` 默认为 3
+- 导入时 `heading-depth` 默认为 4
 - 单根节点的 OPML 会将根作为文件标题
 - 多根节点的 OPML 每个顶级节点成为 H2
 - OPML 中的 `_note` 属性会保留为节点备注
@@ -233,7 +233,7 @@ maxDepth: 4
 mindctx: true              # 标识为 MindCtx 文件（必需，或使用 .mind.md 后缀）
 version: 1                 # 格式版本
 default-view: outline      # 打开时的默认视图（outline / mindmap）
-heading-depth: 3           # 标题最大深度
+heading-depth: 4           # 标题最大深度
 ---
 ```
 
diff --git a/docs/快速上手.md b/docs/快速上手.md
@@ -80,7 +80,7 @@ MindCtx 不使用专有格式。你的大纲数据始终是标准 Markdown：
 
 ```markdown
 ---
-heading-depth: 3
+heading-depth: 4
 ---
 ```
 
diff --git a/examples/产品需求文档.mind.md b/examples/产品需求文档.mind.md
@@ -1,7 +1,7 @@
 ---
 mindctx: true
 default-view: outline
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 产品需求文档：在线协作白板
diff --git a/examples/年度学习计划.mind.md b/examples/年度学习计划.mind.md
@@ -1,7 +1,7 @@
 ---
 mindctx: true
 default-view: mindmap
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 2024 年度学习计划
diff --git a/examples/技术架构设计.mind.md b/examples/技术架构设计.mind.md
@@ -1,7 +1,7 @@
 ---
 mindctx: true
 default-view: outline
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 创业公司技术架构
diff --git a/examples/旅行计划-杭州三日游.mind.md b/examples/旅行计划-杭州三日游.mind.md
@@ -1,7 +1,7 @@
 ---
 mindctx: true
 default-view: mindmap
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 周末旅行计划：杭州三日游
diff --git a/examples/面试准备清单.mind.md b/examples/面试准备清单.mind.md
@@ -1,7 +1,7 @@
 ---
 mindctx: true
 default-view: outline
-heading-depth: 3
+heading-depth: 4
 ---
 
 # 面试准备清单
diff --git a/packages/core/src/importers/freemind.ts b/packages/core/src/importers/freemind.ts
@@ -4,7 +4,7 @@ export function importFreeMind(xmlText: string, fileName: string): string {
   const rootNode = doc.querySelector('map > node');
   if (!rootNode) throw new Error('FreeMind 格式错误: 缺少根节点');
 
-  const headingDepth = 3;
+  const headingDepth = 4;
   const title = rootNode.getAttribute('TEXT') || fileName.replace(/\.mind\.md$/, '');
 
   function convert(node: Element, depth: number): string {
diff --git a/packages/core/src/importers/opml.ts b/packages/core/src/importers/opml.ts
@@ -11,7 +11,7 @@ export function importOPML(opmlText: string, fileName: string): string {
   if (!body) throw new Error('OPML 格式错误: 缺少 body 元素');
 
   const title = doc.querySelector('head > title')?.textContent || fileName.replace(/\.mind\.md$/, '');
-  const headingDepth = 3;
+  const headingDepth = 4;
 
   function convertOutline(element: Element, depth: number): string {
     const text = element.getAttribute('text') || element.getAttribute('TEXT') || '';
diff --git a/packages/core/src/parser.ts b/packages/core/src/parser.ts
@@ -243,7 +243,7 @@ export function parse(markdown: string, options?: ParseOptions): MindCtxTree {
   // Determine headingDepth
   const headingDepth = normalizeHeadingDepth(
     frontmatter['heading-depth'],
-    normalizeHeadingDepth(options?.defaultHeadingDepth, 3)
+    normalizeHeadingDepth(options?.defaultHeadingDepth, 4)
   );
 
   // Step 3: Create virtual root
diff --git a/packages/core/tests/fixtures/complex.mind.md b/packages/core/tests/fixtures/complex.mind.md
@@ -2,7 +2,7 @@
 mindctx: true
 version: 1
 default-view: outline
-heading-depth: 3
+heading-depth: 4
 ---
 
 # Agent 工程能力体系
diff --git a/packages/core/tests/operations.test.ts b/packages/core/tests/operations.test.ts
@@ -4,6 +4,7 @@ import type { MindCtxTree } from '@mindctx/core';
 
 const simpleMd = `---
 mindctx: true
+heading-depth: 3
 ---
 
 # Root
@@ -239,7 +240,7 @@ describe('Operations', () => {
 
     applyOperation(tree, { type: 'toggleCheck', nodeId: h1.id });
 
-    expect(serialize(tree).startsWith('---\nmindctx: true\n---\n\n- [ ] Root\n')).toBe(true);
+    expect(serialize(tree).startsWith('---\nmindctx: true\nheading-depth: 3\n---\n\n- [ ] Root\n')).toBe(true);
   });
 
   test('操作后节点 dirty=true', () => {
@@ -348,7 +349,8 @@ describe('Operations', () => {
   });
 
   test('indent then outdent restores original state', () => {
-    const localTree = parse(simpleMd, { defaultHeadingDepth: 2 });
+    const shallowMd = `---\nmindctx: true\nheading-depth: 2\n---\n\n# Root\n\n## Child A\n\n- Item 1\n- Item 2\n- Item 3\n\n## Child B\n\n- Item B1\n`;
+    const localTree = parse(shallowMd);
     const h1 = localTree.root.children[0];
     const childA = h1.children[0];
     const item2Id = childA.children[1].id;
diff --git a/packages/core/tests/opml.test.ts b/packages/core/tests/opml.test.ts
@@ -176,7 +176,7 @@ function makeTree(root: NodeInput): MindCtxTree {
     filePath: '',
     frontmatter: {},
     rawFrontmatter: '',
-    headingDepth: 3,
+    headingDepth: 4,
     root: makeNode(root, 0),
     metadata: { parseTime: 0, nodeCount: 0, maxDepth: 0 },
   };
@@ -270,13 +270,14 @@ describe('importOPML', () => {
   });
 
   test('handles deep nesting beyond heading depth as nested lists', () => {
-    const markdown = importOPML('<opml><body><outline text="Root"><outline text="A"><outline text="B"><outline text="C"><outline text="D"/></outline></outline></outline></outline></body></opml>', 'deep.opml');
+    const markdown = importOPML('<opml><body><outline text="Root"><outline text="A"><outline text="B"><outline text="C"><outline text="D"><outline text="E"/></outline></outline></outline></outline></outline></body></opml>', 'deep.opml');
 
     expect(markdown).toContain('# Root');
     expect(markdown).toContain('## A');
     expect(markdown).toContain('### B');
-    expect(markdown).toContain('- C');
-    expect(markdown).toContain('  - D');
+    expect(markdown).toContain('#### C');
+    expect(markdown).toContain('- D');
+    expect(markdown).toContain('  - E');
   });
 
   test('handles empty text and notes', () => {
diff --git a/packages/core/tests/parser.test.ts b/packages/core/tests/parser.test.ts
@@ -133,39 +133,39 @@ describe('Parser', () => {
     expect(tree.frontmatter['mindctx']).toBe(true);
     expect(tree.frontmatter['version']).toBe(1);
     expect(tree.frontmatter['default-view']).toBe('outline');
-    expect(tree.frontmatter['heading-depth']).toBe(3);
+    expect(tree.frontmatter['heading-depth']).toBe(4);
   });
 
   test('无 frontmatter 使用默认值', () => {
     const tree = parse(fixture('no-frontmatter.mind.md'));
     expect(tree.frontmatter).toEqual({});
-    expect(tree.headingDepth).toBe(3);
+    expect(tree.headingDepth).toBe(4);
     expect(tree.rawFrontmatter).toBe('');
   });
 
   test('heading-depth 正确读取', () => {
     const tree = parse(fixture('complex.mind.md'));
-    expect(tree.headingDepth).toBe(3);
+    expect(tree.headingDepth).toBe(4);
   });
 
   test('heading-depth 优先级: frontmatter > options > default', () => {
-    // frontmatter has heading-depth: 3 in complex.mind.md
+    // frontmatter has heading-depth: 4 in complex.mind.md
     const tree1 = parse(fixture('complex.mind.md'), { defaultHeadingDepth: 6 });
-    expect(tree1.headingDepth).toBe(3); // frontmatter wins
+    expect(tree1.headingDepth).toBe(4); // frontmatter wins
 
     // no-frontmatter.mind.md has no heading-depth
     const tree2 = parse(fixture('no-frontmatter.mind.md'), { defaultHeadingDepth: 5 });
     expect(tree2.headingDepth).toBe(5); // options win
 
-    // no frontmatter, no options => default 3
+    // no frontmatter, no options => default 4
     const tree3 = parse(fixture('no-frontmatter.mind.md'));
-    expect(tree3.headingDepth).toBe(3);
+    expect(tree3.headingDepth).toBe(4);
   });
 
   test('heading-depth 会解析字符串并限制在 1 到 6', () => {
     expect(parse('---\nheading-depth: "5"\n---\n\n# Title\n').headingDepth).toBe(5);
     expect(parse('---\nheading-depth: 99\n---\n\n# Title\n').headingDepth).toBe(6);
-    expect(parse('---\nheading-depth: invalid\n---\n\n# Title\n').headingDepth).toBe(3);
+    expect(parse('---\nheading-depth: invalid\n---\n\n# Title\n').headingDepth).toBe(4);
   });
 
   test('节点 ID 不重复', () => {
diff --git a/packages/obsidian/src/settings/settings.ts b/packages/obsidian/src/settings/settings.ts
@@ -15,7 +15,7 @@ export interface MindCtxSettings {
 
 export const DEFAULT_SETTINGS: MindCtxSettings = {
   defaultView: 'outline',
-  defaultHeadingDepth: 3,
+  defaultHeadingDepth: 4,
   mindmapDirection: 'side',
   autoSaveDelay: 300,
   enableVirtualScroll: true,
diff --git a/packages/vscode/README.md b/packages/vscode/README.md
@@ -77,7 +77,7 @@ Configure in VS Code Settings (Ctrl+,) under "MindCtx":
 | Setting | Default | Description |
 |---------|---------|-------------|
 | `mindctx.defaultView` | outline | Default view when opening files |
-| `mindctx.headingDepth` | 3 | Maximum heading depth (deeper = list items) |
+| `mindctx.headingDepth` | 4 | Maximum heading depth (deeper = list items) |
 | `mindctx.autoSaveDelay` | 300 | Auto-save debounce in milliseconds |
 | `mindctx.outlineFontSize` | 14 | Outline view font size (px) |
 | `mindctx.showNotePreview` | true | Show note preview next to titles |
diff --git a/packages/vscode/src/MindCtxEditorProvider.ts b/packages/vscode/src/MindCtxEditorProvider.ts
@@ -392,7 +392,7 @@ export class MindCtxEditorProvider
     const config = vscode.workspace.getConfiguration('mindctx');
     return {
       defaultView: config.get<'outline' | 'mindmap'>('defaultView', 'outline'),
-      headingDepth: config.get<number>('headingDepth', 3),
+      headingDepth: config.get<number>('headingDepth', 4),
       autoSaveDelay: config.get<number>('autoSaveDelay', 300),
       outlineFontSize: config.get<number>('outlineFontSize', 14),
       showNotePreview: config.get<boolean>('showNotePreview', true),
diff --git a/packages/vscode/src/extension.ts b/packages/vscode/src/extension.ts
@@ -36,7 +36,7 @@ async function createNewFile(): Promise<void> {
   });
   if (!uri) return;
 
-  const template = `---\nmindctx: true\nheading-depth: 3\n---\n\n# New Document\n\n## Section 1\n\n- Item 1\n- Item 2\n`;
+  const template = `---\nmindctx: true\nheading-depth: 4\n---\n\n# New Document\n\n## Section 1\n\n- Item 1\n- Item 2\n`;
   await vscode.workspace.fs.writeFile(uri, new TextEncoder().encode(template));
   await vscode.commands.executeCommand('vscode.openWith', uri, 'mindctx.editor');
 }
diff --git a/packages/vscode/src/webview/WebviewBridge.ts b/packages/vscode/src/webview/WebviewBridge.ts
@@ -15,7 +15,7 @@ export class WebviewBridge {
   readonly tree: Signal<MindCtxTree | null> = signal(null);
   readonly settings: Signal<MindCtxSettings> = signal({
     defaultView: 'outline',
-    headingDepth: 3,
+    headingDepth: 4,
     autoSaveDelay: 300,
     outlineFontSize: 14,
     showNotePreview: true,
