From db1765c90e491302929af0c1fa27b96b11d8a7e5 Mon Sep 17 00:00:00 2001 From: Turtle Date: Fri, 31 Jul 2026 13:43:03 +0800 Subject: [PATCH 1/2] fix(docs): index persistence events in page outline --- scripts/project-doc-site.spec.ts | 19 +++++++++++++++++-- scripts/project-doc-site.ts | 17 ++++++++++------- website/docs.ts | 9 +++++++-- 3 files changed, 34 insertions(+), 11 deletions(-) diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts index 3892a0e5f3..bfba11f034 100644 --- a/scripts/project-doc-site.spec.ts +++ b/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', () => { diff --git a/scripts/project-doc-site.ts b/scripts/project-doc-site.ts index 8d68aac7a6..592bbcfdee 100644 --- a/scripts/project-doc-site.ts +++ b/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. - * @returns Markdown with an `editSource` frontmatter field. + * @param page Publication manifest entry for the content. + * @returns Markdown with projection-owned frontmatter fields. */ -export function addProjectionFrontmatter(markdown: string, sourcePath: string): string { - const field = `editSource: ${JSON.stringify(sourcePath)}` - if (markdown.startsWith('---\n')) return markdown.replace('---\n', `---\n${field}\n`) - return `---\n${field}\n---\n\n${markdown}` +export function addProjectionFrontmatter(markdown: string, page: Pick): string { + const fields = [ + `editSource: ${JSON.stringify(page.source)}`, + ...(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)) } } diff --git a/website/docs.ts b/website/docs.ts index a640d01e18..09d61d49bb 100644 --- a/website/docs.ts +++ b/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 section: Record order: number + outline?: DocsPage['outline'] sourceAliases?: string[] | Partial> } @@ -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'], - ] as const).map(([source, route, rootLabel, enLabel], order): MirroredPage => ({ + ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', [2, 4]], + ] 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'], From d4a93cbc1a3d9a41fcacc81d8d71d1d2e36c227d Mon Sep 17 00:00:00 2001 From: Turtle Date: Fri, 31 Jul 2026 13:47:51 +0800 Subject: [PATCH 2/2] fix(docs): index the full persistence outline --- scripts/project-doc-site.spec.ts | 2 +- website/docs.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/project-doc-site.spec.ts b/scripts/project-doc-site.spec.ts index bfba11f034..185acf2db5 100644 --- a/scripts/project-doc-site.spec.ts +++ b/scripts/project-doc-site.spec.ts @@ -221,7 +221,7 @@ describe('docsPages locale routes', () => { 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]]) + expect(pages.map(page => page.outline)).toEqual(['deep', 'deep']) }) }) diff --git a/website/docs.ts b/website/docs.ts index 09d61d49bb..8d42ae3209 100644 --- a/website/docs.ts +++ b/website/docs.ts @@ -292,7 +292,7 @@ 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', [2, 4]], + ['docs/persistence-catalog.md', 'reference/persistence-catalog.md', '持久化事件', 'Persistence events', 'deep'], ] as const).map(([source, route, rootLabel, enLabel, outline], order): MirroredPage => ({ source, route,