TOF-445: Title-to-query alignment pass across 38 docs pages by Copilot · Pull Request #178 · mixpanel/docs

Copilot · 2026-08-18T18:55:18Z

Retitles 38 pages whose frontmatter title was 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

38 frontmatter title: fields updated
API reference pages named for their API: Overview → Ingestion API Overview, Authentication → Query API Authentication, Limits → User Profile API Limits
Duplicate concept pages disambiguated by direction of data flow: Segment becomes Segment: Export Mixpanel Cohorts to Segment in Cohort Sync and Segment: Send Event Data to Mixpanel in Tracking Methods. Same for mParticle and Google Cloud Storage, each of which appears in two groups.
sidebarTitle restored on 33 pages so the nav keeps its short labels. Without it the sidebar would read QUERY 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-query was 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/funnels is 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/limits kept its Lexicon prefix to stay parallel with its two siblings.

Title-to-target-query mapping

Page	New title	Target query
`reference/ingestion-api`	Ingestion API Overview	how do I send events to Mixpanel via API
`reference/query-api`	Query API Overview	how do I query Mixpanel reports programmatically
`reference/insights-query`	Insights Query API	how do I use the Mixpanel Insights query API
`reference/funnels-query`	Funnels Query API (Maintenance Mode)	is the Mixpanel funnels query API deprecated
`reference/track-event`	Track Events API (/track)	mixpanel /track endpoint
`docs/tracking-methods/autocapture`	Autocapture: Automatically Track Frontend Events	what is Mixpanel Autocapture
`docs/tracking-methods/integrations/segment`	Segment: Send Event Data to Mixpanel	how do I send Segment data to Mixpanel
`docs/cohort-sync/integrations/segment`	Segment: Export Mixpanel Cohorts to Segment	how do I sync Mixpanel cohorts to Segment

Note 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.

linear-code · 2026-08-18T18:55:22Z

TOF-445

Co-authored-by: tylergoerzen-mxp <259741734+tylergoerzen-mxp@users.noreply.github.com>

mintlify · 2026-08-18T18:59:44Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
mixpanel-docs	🟢 Ready	View Preview	Oct 2, 2026, 9:41 PM

greptile-apps · 2026-08-18T19:02:17Z

Confidence Score: 5/5

[Low risk] Documentation page titles and sidebar labels updated.

The PR appears safe to merge; no outstanding findings were identified.

_{Reviews (9) · Last reviewed commit: "Merge branch 'main' into copilot/tof-445..."}

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>

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>

…tof-445-title-to-query-alignment

tylergoerzen-mxp

Reviewed the diff — all 41 changes are frontmatter title/sidebarTitle only, no content or slugs touched. Colons are properly quoted so the YAML build fix holds, and the new titles resolve the duplicate-title groups described in the PR. LGTM.

tylergoerzen-mxp · 2026-09-25T19:46:26Z

Synced with main. Needs a fresh CODEOWNER approval on the latest push before it can merge — @mbocianski, mind re-approving?

…es, OpenAPI (#180) * Initial plan * Add docs CI gates: frontmatter, code samples, links, redirects Co-authored-by: tylergoerzen-mxp <259741734+tylergoerzen-mxp@users.noreply.github.com> * Fix false positives and false negatives in the docs CI gates check_redirects.py - Honour wildcard redirect sources when resolving a destination. The docstring says chained redirects are allowed, but only exact sources were matched, so the 461 wildcard sources were ignored. That produced 25 errors on main of which only 3 were real: an 88% false-positive rate that would have fired again on the next redirect anyone added. - Detect loops. Every node in a cycle is also a source, so the chained-redirect rule silently swallowed /self -> /self and /a -> /b -> /a. check_links.py - Blank out fenced and inline code before extracting links, so a page documenting an example <a href="/docs/..."> does not fail CI. Line numbers are preserved. check_code_samples.py - Track fence length so a ```python block nested in a ````mdx block does not close the outer block early. Drop the unused FENCE_OPEN_RE and report repo-relative paths instead of absolute ones. check_frontmatter.py - An empty title no longer passes. Verified: all four pass on this branch, and each rejects a deliberate bad fixture (empty title, bare fence, dead link, redirect loop). Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * Add OpenAPI gate, enforce description and unique titles, pin actions 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> * Baseline existing violations so the gates only block new ones; reject redirect chains; validate OpenAPI examples The frontmatter gate failed on main content (362 pages missing a description, 14 duplicate-title groups), so it would have blocked every unrelated PR. Known violations now live in scripts/docs-ci-baseline.json and only new ones fail. Entries that get fixed are reported, never fatal, so TOF-439 (#172) and TOF-441 (#174) can land without touching it. - check_redirects: reject chains (destination is itself redirected); 229 existing chains baselined for #174. Loops reported once per cycle. - check_openapi: validate media-type, parameter and schema-level examples against their schemas; fix the one invalid GDPR example. - check_code_samples: tag two bare fences that landed on main. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Stop tracking Python bytecode Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Note the baseline in the workflow Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Fail wildcard redirect destinations that match no page Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> * Fix docs CI violations on pages added since the gates were written Add missing descriptions to agent-intelligence and wingify, and tag three bare code fences in audit-log-streaming as text. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: tylergoerzen-mxp <259741734+tylergoerzen-mxp@users.noreply.github.com> Co-authored-by: Tyler Goerzen <tyler.goerzen@mixpanel.com> Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: no value <270450525+hywel-mixpanel@users.noreply.github.com> Co-authored-by: hywel-mixpanel <hywel.wong@mixpanel.com>

Initial plan

e0a0055

Copilot AI assigned Copilot and tylergoerzen-mxp Aug 18, 2026

Copilot started work on behalf of tylergoerzen-mxp August 18, 2026 18:55 View session

fix: title-to-query alignment pass across docs pages (TOF-445)

72dcc4f

Co-authored-by: tylergoerzen-mxp <259741734+tylergoerzen-mxp@users.noreply.github.com>

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

Copilot finished work on behalf of tylergoerzen-mxp August 18, 2026 19:00

Copilot AI requested a review from tylergoerzen-mxp August 18, 2026 19:00

greptile-apps Bot reviewed Aug 18, 2026

View reviewed changes

Comment thread docs/cohort-sync/integrations/mparticle.mdx Outdated

mintlify Bot deployed to staging August 18, 2026 19:05 View deployment

mintlify Bot deployed to staging August 18, 2026 20:26 View deployment

mintlify Bot deployed to staging August 20, 2026 06:38 View deployment

tylergoerzen-mxp marked this pull request as ready for review August 20, 2026 07:13

tylergoerzen-mxp requested a review from a team as a code owner August 20, 2026 07:13

tylergoerzen-mxp requested a review from mbocianski August 20, 2026 07:13

tylergoerzen-mxp changed the title ~~Title-to-query alignment pass across docs pages~~ TOF-445: Title-to-query alignment pass across 38 docs pages Aug 20, 2026

tylergoerzen-mxp mentioned this pull request Aug 20, 2026

TOF-447: Add docs CI gates: frontmatter, links, redirects, code samples, OpenAPI #180

Merged

mbocianski approved these changes Sep 24, 2026

View reviewed changes

Merge branch 'main' of https://github.com/mixpanel/docs into copilot/…

5f2acb6

…tof-445-title-to-query-alignment

mbocianski approved these changes Sep 24, 2026

View reviewed changes

mintlify Bot deployed to staging September 24, 2026 20:09 View deployment

mintlify Bot deployed to staging September 24, 2026 20:10 View deployment

tylergoerzen-mxp approved these changes Sep 24, 2026

View reviewed changes

Merge branch 'main' into copilot/tof-445-title-to-query-alignment

d69c782

tylergoerzen-mxp requested a review from mbocianski September 25, 2026 19:46

mintlify Bot deployed to staging September 25, 2026 19:47 View deployment

Merge branch 'main' into copilot/tof-445-title-to-query-alignment

9785859

mintlify Bot deployed to staging September 25, 2026 20:16 View deployment

mbocianski approved these changes Sep 28, 2026

View reviewed changes

Merge branch 'main' into copilot/tof-445-title-to-query-alignment

6fff974

mintlify Bot deployed to staging September 28, 2026 19:51 View deployment

Merge branch 'main' into copilot/tof-445-title-to-query-alignment

aaf4976

tylergoerzen-mxp requested review from a team and junhouse and removed request for a team October 2, 2026 21:41

mintlify Bot deployed to staging October 2, 2026 21:41 View deployment

Navigation Menu

TOF-445: Title-to-query alignment pass across 38 docs pages - #178

TOF-445: Title-to-query alignment pass across 38 docs pages#178
tylergoerzen-mxp with Copilot wants to merge 9 commits into
mainfrom
copilot/tof-445-title-to-query-alignment

Copilot AI commented Aug 18, 2026 •

edited by tylergoerzen-mxp

Loading

Uh oh!

linear-code Bot commented Aug 18, 2026

Uh oh!

mintlify Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Aug 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

tylergoerzen-mxp left a comment

Uh oh!

tylergoerzen-mxp commented Sep 25, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

Copilot AI commented Aug 18, 2026 • edited by tylergoerzen-mxp Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Why this matters for AEO

Changes

Build fix

Accuracy corrections

Title-to-target-query mapping

Note on sequencing

Uh oh!

linear-code Bot commented Aug 18, 2026

Uh oh!

mintlify Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot commented Aug 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Uh oh!

Uh oh!

tylergoerzen-mxp left a comment

Choose a reason for hiding this comment

Uh oh!

tylergoerzen-mxp commented Sep 25, 2026

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Copilot AI commented Aug 18, 2026 •

edited by tylergoerzen-mxp

Loading

mintlify Bot commented Aug 18, 2026 •

edited

Loading

greptile-apps Bot commented Aug 18, 2026 •

edited

Loading