Remove redundant Overview headings on TOC-enabled docs pages#721
Remove redundant Overview headings on TOC-enabled docs pages#721
Conversation
Agent-Logs-Url: https://github.com/microsoft/aspire.dev/sessions/f4bf8607-2b13-4b2b-b41e-ae87dc850586 Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Removes redundant Overview headings from TOC-enabled docs pages and adds enforcement to prevent reintroducing them.
Changes:
- Updated multiple docs pages to remove or rename
## Overviewsections. - Extended doc-writer guidance to forbid
## Overviewon TOC-enabled pages. - Added a docs unit test that fails when TOC-enabled docs include an explicit “Overview” heading.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| src/frontend/tests/unit/filetree-format.vitest.test.ts | Adds detection + unit-test enforcement for explicit “Overview” headings on TOC-enabled docs pages |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx | Renames Overview heading to a more specific “Key capabilities” section |
| src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started.mdx | Renames Overview heading to a more specific “Key capabilities” section |
| src/frontend/src/content/docs/deployment/pipelines.mdx | Renames Overview heading to “Pipeline deployment model” |
| src/frontend/src/content/docs/deployment/custom-deployments.mdx | Removes redundant Overview heading so intro content is direct body text |
| src/frontend/src/content/docs/deployment/azure/azure-security-best-practices.mdx | Removes redundant Overview heading so intro content is direct body text |
| .github/skills/doc-writer/SKILL.md | Documents the “no ## Overview on TOC-enabled pages” guidance and suggested alternatives |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| let currentFence: string | null = null; | ||
|
|
||
| for (const [index, line] of lines.entries()) { | ||
| const fenceMatch = line.match(/^\s*(```+|~~~+)/); | ||
| if (fenceMatch) { | ||
| const fence = fenceMatch[1][0]; | ||
| currentFence = currentFence === fence ? null : fence; | ||
| continue; |
There was a problem hiding this comment.
The code-fence tracker only stores the fence character (` or ~) and toggles on any subsequent fence line starting with the same character. This breaks for valid Markdown that uses longer fences (e.g., opening with ```` and containing ``` inside), causing the scanner to exit the fenced block early and potentially flag headings that are actually inside code blocks. Track the full fence delimiter (character + length) and only close when encountering a matching delimiter with the same character and length >= the opener.
| let currentFence: string | null = null; | |
| for (const [index, line] of lines.entries()) { | |
| const fenceMatch = line.match(/^\s*(```+|~~~+)/); | |
| if (fenceMatch) { | |
| const fence = fenceMatch[1][0]; | |
| currentFence = currentFence === fence ? null : fence; | |
| continue; | |
| let currentFence: { char: '`' | '~'; length: number } | null = null; | |
| for (const [index, line] of lines.entries()) { | |
| const fenceMatch = line.match(/^\s*((`{3,})|(~{3,}))/); | |
| if (fenceMatch) { | |
| const fenceDelimiter = fenceMatch[1]; | |
| const fenceChar = fenceDelimiter[0] as '`' | '~'; | |
| const fenceLength = fenceDelimiter.length; | |
| if (!currentFence) { | |
| currentFence = { char: fenceChar, length: fenceLength }; | |
| continue; | |
| } | |
| if (currentFence.char === fenceChar && fenceLength >= currentFence.length) { | |
| currentFence = null; | |
| continue; | |
| } |
| const frontendRoot = path.resolve(testsDir, '..', '..'); | ||
| const docsRoot = path.join(frontendRoot, 'src', 'content', 'docs'); | ||
| const fileTreeBlockPattern = /<FileTree\b[^>]*>([\s\S]*?)<\/FileTree>/g; | ||
| const frontmatterPattern = /^---\r?\n([\s\S]*?)\r?\n---/; |
There was a problem hiding this comment.
The frontmatter detection is anchored at the start of the file and won’t match if the document begins with a UTF-8 BOM or leading blank lines. In those cases, isTableOfContentsEnabled() will treat TOC as enabled and may produce unexpected failures. Consider permitting an optional BOM and leading whitespace/newlines before the opening ---.
| const frontmatterPattern = /^---\r?\n([\s\S]*?)\r?\n---/; | |
| const frontmatterPattern = /^\uFEFF?\s*---\r?\n([\s\S]*?)\r?\n---/; |
| const frontmatterMatch = source.match(frontmatterPattern); | ||
| const frontmatter = frontmatterMatch?.[1] ?? ''; |
There was a problem hiding this comment.
The frontmatter detection is anchored at the start of the file and won’t match if the document begins with a UTF-8 BOM or leading blank lines. In those cases, isTableOfContentsEnabled() will treat TOC as enabled and may produce unexpected failures. Consider permitting an optional BOM and leading whitespace/newlines before the opening ---.
| if (/^\s*##+\s+Overview\s*$/.test(line)) { | ||
| issues.push({ | ||
| line: index + 1, | ||
| reason: | ||
| 'TOC-enabled pages must not include an explicit "Overview" heading; use intro text or a more specific heading.', | ||
| }); | ||
| } |
There was a problem hiding this comment.
This enforcement currently flags any heading level ## or deeper (##+) and only matches the exact-cased word Overview. However, the added guidance in doc-writer specifically references forbidding ## Overview. Either (a) adjust the rule/message/docs to be consistent about whether ### Overview is also prohibited, and (b) consider making the match case-insensitive so ## overview can’t bypass the rule.
Summary
Overviewheadings from affected docs pages and keep/rename content where needed.doc-writerskill guidance to explicitly forbid## Overviewon TOC-enabled pages.Overviewheading.Updated articles
src/frontend/src/content/docs/deployment/custom-deployments.mdxsrc/frontend/src/content/docs/deployment/azure/azure-security-best-practices.mdxsrc/frontend/src/content/docs/deployment/pipelines.mdx(Overviewrenamed toPipeline deployment model)src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-host.mdx(Overviewrenamed toKey capabilities)src/frontend/src/content/docs/integrations/cloud/azure/azure-container-registry/azure-container-registry-get-started.mdx(Overviewrenamed toKey capabilities)Validation
pnpm --dir ./src/frontend run lintpnpm --dir ./src/frontend run test:unit:docspnpm --dir ./src/frontend run build:skip-searchpnpm --dir ./src/frontend run test:unitparallel_validationrun: Code review succeeded; CodeQL timed out per tool warning.