fix(docs): index persistence events in page outline

scripts/project-doc-site.spec.ts

@@ -217,20 +217,35 @@ describe('docsPages locale routes', () => {
       expect(english?.section).toBe('Cordis Core API')
     }
   })
+
+  it('includes persistence event headings in both locale outlines', () => {
+    const pages = docsPages.filter(page => page.source === 'docs/persistence-catalog.md')
+    expect(pages).toHaveLength(2)
+    expect(pages.map(page => page.outline)).toEqual([[2, 4], [2, 4]])
+  })
 })
 
 describe('addProjectionFrontmatter', () => {
   it('adds frontmatter to an ordinary Markdown page', () => {
-    expect(addProjectionFrontmatter('# Guide\n', 'docs/guide.md')).toBe(
+    expect(addProjectionFrontmatter('# Guide\n', { source: 'docs/guide.md' })).toBe(
       '---\neditSource: "docs/guide.md"\n---\n\n# Guide\n',
     )
   })
 
   it('extends existing VitePress frontmatter', () => {
-    expect(addProjectionFrontmatter('---\nlayout: home\n---\n', 'docs/index.md')).toBe(
+    expect(addProjectionFrontmatter('---\nlayout: home\n---\n', { source: 'docs/index.md' })).toBe(
       '---\neditSource: "docs/index.md"\nlayout: home\n---\n',
     )
   })
+
+  it('adds the page-specific outline depth from the publication manifest', () => {
+    expect(addProjectionFrontmatter('# Catalog\n', {
+      source: 'docs/catalog.md',
+      outline: [2, 4],
+    })).toBe(
+      '---\neditSource: "docs/catalog.md"\noutline: [2,4]\n---\n\n# Catalog\n',
+    )
+  })
 })
 
 describe('projectedPageContent', () => {

scripts/project-doc-site.ts

@@ -259,13 +259,16 @@ export function rewriteMarkdown(source: string, options: RewriteMarkdownOptions)
  * Record the canonical edit target in VitePress frontmatter.
  *
  * @param markdown Projected Markdown content.
- * @param sourcePath Repository-relative canonical source path.
+ * @param page Publication manifest entry for the content.
- * @returns Markdown with an `editSource` frontmatter field.
+ * @returns Markdown with projection-owned frontmatter fields.
  */
-export function addProjectionFrontmatter(markdown: string, sourcePath: string): string {
+export function addProjectionFrontmatter(markdown: string, page: Pick<DocsPage, 'source' | 'outline'>): string {
-  const field = `editSource: ${JSON.stringify(sourcePath)}`
+  const fields = [
-  if (markdown.startsWith('---\n')) return markdown.replace('---\n', `---\n${field}\n`)
+    `editSource: ${JSON.stringify(page.source)}`,
-  return `---\n${field}\n---\n\n${markdown}`
+    ...(page.outline === undefined ? [] : [`outline: ${JSON.stringify(page.outline)}`]),
+  ].join('\n')
+  if (markdown.startsWith('---\n')) return markdown.replace('---\n', `---\n${fields}\n`)
+  return `---\n${fields}\n---\n\n${markdown}`
 }
 
 /**
@@ -317,6 +320,6 @@ export function projectDocs(): void {
       repoRoot: root,
       repositoryRef,
     })
-    writeFileSync(output, addProjectionFrontmatter(projectedPageContent(projected, page), page.source))
+    writeFileSync(output, addProjectionFrontmatter(projectedPageContent(projected, page), page))
   }
 }

website/docs.ts

@@ -37,6 +37,8 @@ export interface DocsPage {
   section: string
   /** Stable order within the section. */
   order: number
+  /** Heading levels included in this page's VitePress outline. */
+  outline?: number | readonly [number, number] | 'deep' | false
   /** Additional repository paths that resolve to this page. */
   sourceAliases?: string[]
 }
@@ -49,6 +51,7 @@ interface MirroredPage {
   sidebar: Record<DocsLocale, DocsSidebar | null>
   section: Record<DocsLocale, string>
   order: number
+  outline?: DocsPage['outline']
   sourceAliases?: string[] | Partial<Record<DocsLocale, string[]>>
 }
 
@@ -79,6 +82,7 @@ function mirroredPages(pages: MirroredPage[]): DocsPage[] {
       sidebar: page.sidebar[locale],
       section: page.section[locale],
       order: page.order,
+      ...(page.outline === undefined ? {} : { outline: page.outline }),
       ...(aliases === undefined ? {} : { sourceAliases: aliases }),
     }
   }))
@@ -288,8 +292,8 @@ const reference = mirroredPages([
     ['docs/tool-catalog.md', 'reference/tool-catalog.md', 'Tool Schema', 'Tool schemas'],
     ['docs/cordis-catalog/services.md', 'reference/cordis-catalog/services.md', '服务', 'Services'],
     ['docs/cordis-catalog/events.md', 'reference/cordis-catalog/events.md', '事件', 'Events'],
-    ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events'],
+    ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', [2, 4]],
-  ] as const).map(([source, route, rootLabel, enLabel], order): MirroredPage => ({
+  ] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({
     source,
     route,
     contentLocale: 'en-US',
@@ -297,6 +301,7 @@ const reference = mirroredPages([
     sidebar: { root: 'zh-reference', en: 'en-reference' },
     section: { root: '生成参考', en: 'Generated reference' },
     order,
+    ...(outline === undefined ? {} : { outline }),
   })),
   ...([
     ['context.md', 'Context', 'Context'],