Improve page metadata: titles, descriptions, and social tags - #1054
Merged
Conversation
…age social tags, lint gate Why: every page's frontmatter title feeds the <title> tag, H1, sidebar label, OG image, llms.txt entry, and the citation label in AI tools (Kapa, Pipecat Context Hub). 42 duplicate titles across 97 pages made those surfaces ambiguous, docs.json pinned one generic og:description site-wide so all pages unfurled identically, and half the descriptions were too thin to disambiguate anything. Titles: short, readable, H1-friendly. Services use vendor + category names (Cartesia Text-to-Speech, Twilio Frame Serializer, Silero VAD); server class-reference pages keep class names (TransportParams, AudioBufferProcessor); SDK/Flows/Cloud reference pages use short names with a disambiguating page-level og:title (Daily WebRTC Transport + og:title 'Daily WebRTC Transport - iOS SDK'); landings are natural phrases (Pipecat Server API Overview, iOS SDK Reference); CLI pages are the literal command (pipecat cloud deploy). Six duplicate title groups (21 pages, cross-SDK transports and Types/Exceptions) are deliberate: each member carries a distinct og:title. Eyebrows switch to breadcrumbs site-wide (styling.eyebrows) so deep pages show their full path. Descriptions: all 455 rewritten or verified - 50-160 chars, carrying the class names and modality acronyms (STT/TTS/LLM/VAD) each page documents; claims grep-verified against page bodies. docs.json: removed site-wide og:description, twitter:description, og:url, twitter:url from seo.metatags (Mintlify derives them per-page); corrected og:image:height to 630. No slugs changed anywhere; all 452 redirects untouched; one new page (enterprise-support). Tooling: scripts/docs-meta-lint.mjs runs in CI (metadata-lint.yml), comparing each PR against its merge-base. Enforced: description uniqueness and effective unfurl-title (og:title||title) uniqueness - the RAG identity invariants. Raw title duplicates warn only. scripts/gen-llms-txt.mjs generates the checked-in structured llms.txt (the auto-generated fallback would sit at 95% of its 100k truncation cap); staleness fails CI. CLAUDE.md documents the conventions and is noindexed. Metrics vs main: duplicate titles 42 -> 6 accepted groups, duplicate descriptions 4 -> 0, descriptions under 70 chars 231 -> 0, description mean 71 -> 111 chars, og:titles 0 -> 58, sidebar labels deliberately changed on 42 API reference pages (vendor-only labels in vendor groups).
Contributor
|
🔍 Mintlify preview for this branch: https://daily-docs-metadata-overhaul.mintlify.site |
jptaylor
marked this pull request as draft
August 4, 2026 01:44
markbackman
reviewed
Aug 4, 2026
| ### MDX frontmatter | ||
|
|
||
| Every page needs a `title` and optional `description`: | ||
| Every page needs a `title` and a `description`. The frontmatter `title` becomes |
Contributor
There was a problem hiding this comment.
Thanks for adding this 🙏
markbackman
reviewed
Aug 4, 2026
| @@ -0,0 +1,782 @@ | |||
| # Pipecat | |||
Contributor
There was a problem hiding this comment.
Yup, much better than the default that Mintlify scrapes together.
markbackman
approved these changes
Aug 4, 2026
markbackman
left a comment
markbackman
left a comment
Contributor
There was a problem hiding this comment.
Ship it when you're ready! Thanks for taking a pass on this.
Landing page at /api-reference with a card for each reference surface: the server framework, each client SDK with docs and GitHub links, Pipecat Flows, the Pipecat Cloud REST API and Python SDK, the CLI, and the Context Hub. Nav walkers in the lint and llms.txt generator learn group root and tab-level pages.
jptaylor
force-pushed
the
docs/metadata-overhaul
branch
from
August 4, 2026 02:36
cface20 to
69c8412
Compare
jamsea
reviewed
Aug 4, 2026
| --- | ||
| title: "Callbacks and Events" | ||
| description: "Handle bot events and state changes with callbacks and event listeners in the Pipecat JavaScript client" | ||
| "og:title": "Callbacks and Events - JavaScript SDK" |
jamsea
reviewed
Aug 4, 2026
| @@ -1,7 +1,7 @@ | |||
| --- | |||
| title: "iOS SDK Overview" | |||
Contributor
There was a problem hiding this comment.
@jptaylor here's an example of a doc without og:title should they all have og:title ?
Contributor
|
@jptaylor my only question is what's the difference between |
jamsea
marked this pull request as ready for review
August 4, 2026 03:11
jamsea
approved these changes
Aug 4, 2026
…overhaul # Conflicts: # .gitignore # CLAUDE.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Improves how docs pages appear in search results, link unfurls, and AI tools that index the docs (llms.txt consumers, Context Hub, Kapa).
Cartesia×2,Quickstart×3, etc.) and normalize naming across services, transports, and SDK reference pages. Sidebar labels are preserved viasidebarTitle.og:description/twitter:*overrides fromdocs.jsonso each page unfurls with its own title and description; add per-pageog:titlewhere short titles repeat across SDKs.llms.txt(generated byscripts/gen-llms-txt.mjs), grouped by section with per-page descriptions.scripts/docs-meta-lint.mjs+ CI workflow) enforcing the invariants: every page has a title and description, descriptions are unique, and unfurl titles are unique.styling.eyebrows) and set the social thumbnail font to Geist./enterprise-support).