Automated SEO fixes: trim long descriptions and expand Factory MCP title - #596
Conversation
Co-Authored-By: Oz <oz-agent@warp.dev>
|
Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have the users @warp-factories[bot] on file. In order for us to review and merge your code, each contributor must visit https://cla.warp.dev to read and agree to our CLA. Once you have done so, please comment |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
This PR was generated with Warp. Comment |
|
I'm starting a first review of this pull request. You can view the conversation on Warp. I completed the review and no human review was requested for this pull request. Comment Powered by Oz |
|
@cla-bot check |
|
The cla-bot has been summoned, and re-checked this pull request! |
![warp-for-oss[bot]](https://avatars.githubusercontent.com/in/3450139?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates SEO metadata on five docs pages by expanding the Factory MCP title and trimming long frontmatter descriptions. The description edits are scoped and there is no approved spec context to compare against.
Concerns
src/content/docs/factories/factory-mcp.mdxadds a Markdown H1 even though Starlight already renders the frontmattertitleas the page H1, which creates duplicate page titles and undermines the SEO/accessibility goal.- Security review: no security-sensitive behavior, auth logic, secrets handling, or executable code changed.
Verdict
Found: 0 critical, 1 important, 0 suggestions
Request changes
Comment /oz-review on this pull request to retrigger a review (up to 3 times on the same pull request).
Powered by Oz
| label: "Factory MCP" | ||
| --- | ||
|
|
||
| # Factory MCP for Warp Factories |
There was a problem hiding this comment.
Remove this H1. Astro/Starlight takes the title from title in the front matter: this creates a duplication. Also, "Factory MCP for Warp Factories" is a little redundant. Is the redundancy worth the improvement in SEO?
There was a problem hiding this comment.
Good catch on both counts. Removed the H1 — you're right that Starlight already renders the frontmatter title as the page's H1, so the added heading was a straight duplicate.
On the redundancy: agreed it wasn't worth it. Reworded the title to Factory MCP for coding agents instead of Factory MCP for Warp Factories — it still clears the title_too_short threshold (30 chars) and describes what the page is actually about (connecting coding agents to factories) without repeating "Factory"/"Factories". Sidebar label stays Factory MCP. Let me know if you'd prefer different wording. See f41eae4.
Starlight already renders the frontmatter title as the page H1, so the explicit H1 added by the SEO fix duplicated the page title. Also reworked the title to avoid repeating "Factory"/"Factories" against the sidebar section context. Co-Authored-By: Warp <agent@warp.dev>
Astro Starlight always renders the page H1 from the frontmatter title (or sidebar label/slug fallback) -- this repo's pages never contain a manual H1 in the markdown body, since that pattern was leftover behavior from the old GitBook-based docs platform. The skill previously told the audit to add or sync an H1 whenever a title or sidebar label changed, which is what produced the duplicate H1 on the Factory MCP page fixed earlier on this branch. Rewrite the guidance so the skill never adds/syncs a manual H1, and instead treats one found during the multiple_h1/missing_h1 checks as an incidental defect to remove. Co-Authored-By: Warp <agent@warp.dev>
![warp-agent-staging[bot]](https://avatars.githubusercontent.com/in/2196476?s=60&v=4){kind=small}
There was a problem hiding this comment.
Overview
This PR updates five SEO metadata entries, removes the Factory MCP duplicate H1, and corrects the SEO-audit guidance. The current source and deployed preview render exactly one H1, Factory MCP for coding agents, and the revised skill consistently forbids adding or synchronizing manual H1s.
Concerns
/factories/factory-mcp/ that shows the single rendered Factory MCP for coding agents H1; the review independently verified that state on the deployed preview, but the evidence must be attached to the PR for merge-time review.
Verdict
Checks: CI ✅ · typecheck ✅ · lint unavailable locally (trunk is not installed) · local build ❌ (the same _llms-txt/support.txt stack overflow occurs on the PR base) · deployed preview H1 ✅
Found: 0 critical, 1 important, 0 suggestions
Request changes
Review run
https://oz.staging.warp.dev/runs/01a026b9-89e1-7415-aa5b-339308b960f3
There was a problem hiding this comment.
Overview
Re-review confirms the requested static visual artifact is now attached to the PR and matches the deployed Factory MCP page. The page renders exactly one H1, Factory MCP for coding agents; the duplicate-H1 fix and the SEO-audit guidance remain correct.
Verdict
Checks: CI ✅ · typecheck ✅ · visual proof ✅ · local build baseline-only failure (the unchanged base also overflows while rendering _llms-txt/support.txt)
Found: 0 critical, 0 important, 0 suggestions
Approve
Review run
https://oz.staging.warp.dev/runs/01a026b9-89e1-7415-aa5b-339308b960f3
1 participant
Summary
SEO audit of docs.warp.dev (377 pages, 11 issues). Fixes one short title and four overlong meta descriptions.
Changes
factories/factory-mcp.mdxFactory MCP→Factory MCP for coding agents(sidebar label unchanged)platform/self-hosting/index.mdxplatform/self-hosting/monitoring.mdxplatform/harnesses/warp-agent.mdxplatform/harnesses/authentication.mdxAllowlisted (not changed)
Changelog, Guides, Tabs, Split panes, Tab Configs, Artifacts — intentionally short titles per skill exceptions.
Verification
factories/factory-mcp.mdx): confirmed the file has no manual H1 in its body, so Starlight renders exactly one H1 (from the frontmattertitle). Verified against the locally-built page (see screenshot below): exactly one H1 renders, "Factory MCP for coding agents"..agents/skills/docs-seo-audit/SKILL.md): skill-doc-only change (testing-exempt perfactory-verification— a test here would only assert a sentence exists in a markdown file, not agent behavior). No repo build/lint target covers.agents/skills/content, so no additional command was run.Rework changes
factories/factory-mcp.mdx(flagged by both the automated review and the requester): Starlight already renders the frontmattertitleas the page's H1, so the explicit# Factory MCP for Warp Factoriesheading this PR had added duplicated the page title. Removed the explicit H1 — confirmed the built page now has exactly one H1 matching the title.Factory MCP for coding agents— still fixes the originaltitle_too_shortwarning (30 chars, within the 20–70 range) and accurately reflects the page's content (connecting coding agents to factories) without repeating "Factory".docs-seo-auditskill told the audit to add/sync a manual H1 whenever a title or sidebar label changed, which is what produced the duplicate H1 above. Rewrote the skill's key principles, duplicate-title fix sections, and review-loop checklist to state that Astro Starlight always renders the page H1 from frontmattertitle(this repo's pages never contain a manual H1 — that pattern was leftover behavior from the old GitBook-based docs platform), and that a manual H1 found during a future audit should be flagged/removed as incidental cleanup rather than kept in sync.npm run dev) and used computer use to load/factories/factory-mcp/, confirming exactly one H1 renders ("Factory MCP for coding agents") with no duplicate heading. Screenshot attached below.Originating thread: https://warpdev.slack.com/archives/C09BVK0PL3Y/p1787354780045419
Computer-use screenshots
The /factories/factory-mcp/ docs page showing the breadcrumb "FACTORIES > INTEGRATIONS" and the single large H1 heading "Factory MCP for coding agents" at the top of the main article content, with its subtitle text below.
Co-Authored-By: Warp agent@warp.dev