TOF-445: Title-to-query alignment pass across 38 docs pages - #178
Open
tylergoerzen-mxp with Copilot wants to merge 4 commits into
Open
TOF-445: Title-to-query alignment pass across 38 docs pages#178tylergoerzen-mxp with Copilot wants to merge 4 commits into
tylergoerzen-mxp with Copilot wants to merge 4 commits into
Conversation
Co-authored-by: tylergoerzen-mxp <259741734+tylergoerzen-mxp@users.noreply.github.com>
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Workflows to automatically generate PRs for you. |
Copilot
AI
changed the title
[WIP] Add title-to-query alignment pass across docs pages
Title-to-query alignment pass across docs pages
Aug 18, 2026
Contributor
Confidence Score: 5/5The PR appears safe to merge. No blocking failure remains.
|
| Filename | Overview |
|---|---|
| docs/cohort-sync/integrations/mparticle.mdx | Quotes the descriptive title and adds a concise sidebar label, resolving the prior frontmatter issue. |
| docs/tracking-methods/autocapture.mdx | Uses a quoted query-aligned title while preserving the original navigation label. |
| reference/ingestion-api.mdx | Disambiguates the rendered API title and retains “Overview” in the sidebar. |
Reviews (4): Last reviewed commit: "Clear the last three duplicate titles" | Re-trigger Greptile
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
Seven titles contained an unquoted colon, which is invalid YAML frontmatter and fails the Mintlify build. Quote every title, and: - funnels.mdx is an index page, so drop the banned colon format - funnels-query.mdx says "maintenance mode" in the body, not "deprecated" - limits.mdx keeps its Lexicon prefix to match its siblings - restore the prior title as sidebarTitle on 33 pages so the nav keeps its short labels instead of "QUERY API > Query API Overview" Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
tylergoerzen-mxp
added a commit
that referenced
this pull request
Aug 20, 2026
Completes rec #20 Part B's gate list. - New check_openapi.py: parses all 14 specs, requires openapi/info/paths, and resolves every local $ref. Uses openapi-spec-validator for full schema validation when installed, and still runs structurally without it. Passes on all 14 specs today; rejects a spec with a dangling $ref. - check_frontmatter.py now requires a non-empty description and fails on duplicate rendered titles, which rec #11 asked for. - Pin actions/checkout and actions/setup-python to commit SHAs, matching stale.yml. Collapse four near-identical jobs into one with ordered steps, and add a concurrency group. MERGE ORDER: the frontmatter gate is red until #172 (description backfill) and #178 (title dedupe) land. Verified against the #172 tree: all description errors clear, leaving only the duplicate titles that #178 resolves. Merge this last, as the plan intends. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Rec #11 asks for a CI uniqueness test on rendered titles, which only passes at zero duplicates. Three pairs survived the first pass: - Data Pipeline Integrations: the old-pipelines copy is now marked (Legacy), keeping "Integrations" as its sidebar label - Lookup Tables: the reference page is the API, so it becomes Lookup Tables API - Mixpanel Headless: the guide gets the benefit-style title, leaving the bare product name to the docs page Verified zero duplicate titles across the tree, so the frontmatter gate in #180 can enforce uniqueness once this and #172 land. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
tylergoerzen-mxp
marked this pull request as ready for review
August 20, 2026 07:13
tylergoerzen-mxp
changed the title
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
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.
Retitles 38 pages whose frontmatter
titlewas a bare label. No slugs, content, or structure touched.Relates to: https://linear.app/mixpanel/issue/TOF-445/aeo-qw8-title-to-query-alignment-pass
Why this matters for AEO
Semantic similarity between a page title and the user's query is the largest single citation predictor measured — 0.602 for cited pages against 0.484 for non-cited, across 1.4M ChatGPT prompts (Ahrefs, Apr 2026). It beats every other on-page factor studied.
The docs had 15 duplicate-title groups covering 46 pages. Twelve API reference pages rendered as "Overview — Mixpanel" and seven as "Authentication — Mixpanel." To a crawler or an LLM those pages are indistinguishable from each other, and they match no query anyone would type. "Authentication" is not a question; "Query API Authentication" is the answer to one.
Slugs were deliberately left alone. Descriptive slugs do correlate with citation (89.8% vs 81.1%), but renaming existing URLs costs redirect churn that outweighs the gain. Slug guidance belongs in the contributor guide for new pages.
Changes
title:fields updatedOverview→Ingestion API Overview,Authentication→Query API Authentication,Limits→User Profile API LimitsSegmentbecomesSegment: Export Mixpanel Cohorts to Segmentin Cohort Sync andSegment: Send Event Data to Mixpanelin Tracking Methods. Same for mParticle and Google Cloud Storage, each of which appears in two groups.sidebarTitlerestored on 33 pages so the nav keeps its short labels. Without it the sidebar would readQUERY API › Query API Overview.Zero duplicate rendered titles remain across the repo.
Build fix
Seven of the new titles contained an unquoted colon, which is invalid YAML frontmatter and fails the Mintlify build with
mapping values are not allowed here. Every pre-existing colon title in the repo is quoted; these were not. All 38 files now parse.Accuracy corrections
reference/funnels-querywas titled "(Deprecated)". The page body says the API "is in maintenance mode," which is a weaker claim. Now "(Maintenance Mode)" — a title should not overstate what the page says.docs/reports/funnelsis an index page (a one-line intro plus a five-card grid). The style guide bans the colon format on index pages; it is now "Funnels Report".reference/limitskept its Lexicon prefix to stay parallel with its two siblings.Title-to-target-query mapping
reference/ingestion-apireference/query-apireference/insights-queryreference/funnels-queryreference/track-eventdocs/tracking-methods/autocapturedocs/tracking-methods/integrations/segmentdocs/cohort-sync/integrations/segmentNote on sequencing
PR #180 adds a CI gate failing the build on duplicate rendered titles. That gate needs this PR merged first. Three duplicate pairs that survived the initial pass — Data Pipeline Integrations, Lookup Tables, Mixpanel Headless — are also resolved here so the gate can go green.