Skip to content

Avoid duplicate rendered titles across Astro docs - #78696

Open
pelikhan wants to merge 4 commits into
mainfrom
pelikhan/smart-docs-titles
Open

pelikhan wants to merge 4 commits into
mainfrom
pelikhan/smart-docs-titles

Conversation

@pelikhan

Copy link
Copy Markdown
Collaborator

Summary

Docs pages such as the Unified Agent Session Specification render the frontmatter title and the same opening Markdown heading twice. Deduplicate matching opening H1s in the shared Astro rendering pipeline instead of editing individual pages.

  • Match visible title text across Markdown and MDX, ignoring inline formatting, capitalization, and whitespace.
  • Preserve existing title anchors and subsequent heading slugs while leaving distinct headings, images, dynamic expressions, and landing-page titles intact.
  • Document the behavior and add sandbox-compatible command guidance for worktrees, temporary caches, and external docs dependencies.

Validation

  • npm --prefix docs run test:titles: 23 production-rendered regression cases passed, including the reported specification page.
  • Strict TypeScript checking passed for the new plugin.
  • python3 scripts/check-instruction-prefixes.py AGENTS.md .github/skills/developer/SKILL.md passed.
  • make agent-report-progress and the final make agent-report-progress-no-test passed.

The full docs build was attempted but is blocked by missing external githubnext/agentics workflow sources required by the existing build configuration.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@pelikhan
pelikhan marked this pull request as ready for review November 17, 2026 09:34
Copilot AI adaptive review requested due to automatic review settings November 17, 2026 09:34
@github-actions

Copy link
Copy Markdown
Contributor

🧠 Matt Pocock Skills Reviewer is reviewing this pull request using Matt Pocock's engineering skills...

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

✅ Test Quality Sentinel completed test quality analysis.

Test Quality Sentinel

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

🧪 Test quality analysis by Test Quality Sentinel · copilot · routed: haiku55 xhigh · ~1 AIC · ⌖ ~2 AIC · ⊞ 7.2K · ◷

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

✅ PR Code Quality Reviewer completed the code quality review.

PR Code Quality Reviewer

Outcome: reported_action

The agent completed and reported one or more actions. The no-op output is a completion signal, not a claim that no action was taken.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt56 · ~3 AIC · ⌖ ~1 AIC · ⊞ 1.5K · ◷

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

✅ Ponytail Reviewer completed successfully!

Ponytail Reviewer

Outcome: reported_no_action

The agent completed and reported no action. A no-op output alone does not verify that all required work was completed or that publication was possible.

Agent messages are omitted from this comment. The category uses structured run status, not interpretation of agent prose.

Generated by Ponytail Reviewer for #78696 · codex · routed: gpt61 medium · ~4 AIC · ⌖ ~1 AIC · ⊞ 185 · ◷

@github-actions

Copy link
Copy Markdown
Contributor

Comment Memory

Peek at saved memory (pr-code-quality-reviewer)
reviewed_at: 2026-11-17T09:38:13Z
review_event: REQUEST_CHANGES
top_themes: [production-pipeline test coverage]
files_reviewed: [docs/tests/page-titles.test.mjs, docs/src/lib/rehype/deduplicateTitle.js, docs/astro.config.mjs]
comment_count: 1
History

Note

This comment is managed by comment memory.

Expand the saved memory block to view or edit the persistent context for this thread.
Edit only the text inside the backtick fences; workflow metadata and the footer are regenerated automatically.

Learn more about comment memory

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt50 · ~3 AIC · ⌖ ~1 AIC · ⊞ 1.5K · ◷
Comment /review to run again

@github-actions github-actions Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I found one blocking test-quality issue: the new regression suite uses a bespoke Astro config and therefore does not validate the production markdown pipeline or plugin ordering. Please make the tests exercise the production configuration (or otherwise cover that wiring) before merge.

🔎 Code quality review by PR Code Quality Reviewer · copilot · gpt50 · ~3 AIC · ⌖ ~1 AIC · ⊞ 1.5K
Comment /review to run again

await mkdir(join(docsRoot, ".astro"), { recursive: true });
root = await mkdtemp(join(docsRoot, ".astro/page-titles-"));
const content = join(root, "src/content/docs");
await mkdir(content, { recursive: true });

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This regression suite builds a separate minimal Astro configuration instead of exercising docs/astro.config.mjs. As a result, it never runs the production remark plugins or the actual rehypeDeduplicateTitle + rehypeTableWrapper ordering, so a wiring/order regression in the real docs pipeline can pass all of these tests. Please either build with the production config (isolating only the fixture content) or add coverage that validates the production configuration itself.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The fixture now uses the production Markdown processor and asserts the production table wrapper output. Committed as 49c548d.

@github-actions

Copy link
Copy Markdown
Contributor

Comment Memory

Peek at saved memory (review-history)
{"id":"ldg-337a5fb6-4956-4b32-b608-5d4cb8ed52c5","parents":[],"payload":{"id":"ldg-d3104317-c789-4a1d-a52d-298ca1c55a5a","operation":"append","value":{"finding_count":1,"head_sha":"5dd913c55c3cf1ec43c2b015156d8dbac04275b9","outcome":"findings"}},"sha":"sha256:ab8dd49f72466eac74d0314e4be489323573ff0350c27dd00053af17c0ba8adf","timestamp":"2026-11-17T09:43:21.797Z","type":"ledger_append","version":1}
History

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Title deduplication can remove a landing page’s only H1 and leave duplicate titles when an MDX comment precedes the opening heading.

2 open issues
What changed in this PR

This PR adds shared Astro title deduplication so documentation pages do not repeat their frontmatter title as an opening Markdown H1.

Changes:

  • Adds a rendering plugin that compares normalized title text and preserves heading anchors.
  • Adds production-rendered Markdown and MDX regression cases and documents the behavior.
  • Adds sandbox guidance for worktrees, temporary caches, and external docs dependencies.
File Description
docs/​tests/​page-titles.test.mjs Adds rendered title and anchor regression tests.
docs/​src/​lib/​rehype/​deduplicateTitle.js Implements matching opening-title deduplication.
docs/​README.md Documents title behavior and the test command.
docs/​package.json Adds the test:titles script.
docs/​astro.config.mjs Registers the shared rendering plugin.
AGENTS.md Adds sandbox-compatible command guidance.
.github/​skills/​developer/​SKILL.md Details worktree, cache, and dependency handling.

Review effort: Balanced (adaptive)

Comment on lines +29 to +30
heading.tagName = "span";
heading.children = [];

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Deduplication now skips the root docs index.md/index.mdx; I added a Markdown landing-page H1 regression case. Committed as 49c548d.

function isContent(node) {
if (node.type === "comment" || node.type === "mdxjsEsm") return false;
if ("value" in node && typeof node.value === "string") {
if (node.type === "text" && !node.value.trim()) return false;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comment-only MDX flow expressions are now ignored, and the MDX fixture places such a comment before the matching H1. Committed as 49c548d.

@gh-aw-bot

Copy link
Copy Markdown
Collaborator

@copilot

🍳 A little prep to help this PR along! Copilot assignment requested for the following outstanding work:

  1. Update this branch with the latest main using make merge-main, resolving any conflicts and preserving the intended changes.
  2. Review (docs/tests/page-titles.test.mjs:51): address unresolved feedback - Review comment
  3. Review (docs/src/lib/rehype/deduplicateTitle.js:30): address unresolved feedback - Review comment
  4. Review (docs/src/lib/rehype/deduplicateTitle.js:38): address unresolved feedback - Review comment
  5. Fix failing check Analyze (python) (FAILURE): Check run.

Keeping the changes focused; human review and CI get the final taste test. No merging or CI triggering.

Structured data
{
  "completed_task": 0,
  "head": "cc8cf84918753fd2abcc8287c99b491712f17056",
  "kind": "requested",
  "schema_version": "1",
  "state": "81d7de2602c4e195022fe3ce70bea2f848ac3ab891dd89e51ddd459821ced91f",
  "work": [
    "35c4c891f9dff635ed610abe02f021bc2117450d8ae8bf8d092685cf9b456cb0",
    "43282e7f5b3023b8c8cf9099eab79e7b99f650965f08b47d3df33cde5589879d",
    "4ca2671bb13933b4ac702a712dfd1adc8119559e8c7c2f60ca9e473cfde787af",
    "5c4bd4c61b3573cfe13e822470eb1ceb829c77c170c1c3459dd613c915ff1df2"
  ],
  "workflow": "pr-sous-chef"
}

Generated by 👨🍳 PR Sous Chef · pi · routed: haiku55 xhigh · ~3 AIC · ⌖ ~2 AIC · ⊞ 7K · ◷
Comment /souschef to run again

gh-aw-bot and others added 2 commits November 17, 2026 10:49
…itles

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants