Skip to content

docs(seo): rewrite top-impression page titles, fix AWX/Makefile search noise#71

Merged
ndreno merged 1 commit intomainfrom
docs/seo-improvements
Apr 29, 2026
Merged

docs(seo): rewrite top-impression page titles, fix AWX/Makefile search noise#71
ndreno merged 1 commit intomainfrom
docs/seo-improvements

Conversation

@ndreno
Copy link
Copy Markdown
Contributor

@ndreno ndreno commented Apr 29, 2026

Summary

  • Reworded SUMMARY.md entries (and matching H1s) for the high-impression docs pages: control plane, middlewares, dispatchers, getting started, CLI reference, dev setup, plugin development, spec configuration
  • Also moved those entries to sentence case
  • Rephrased the parenthetical and heading on control-plane.md that contained the exact phrase 'running the UI development', which was attracting AWX/Makefile-related search traffic

Why

Last 90 days of Search Console data:

Page Impressions Avg position Clicks
guide/control-plane.html 151 2.34 0
guide/middlewares.html 79 6.68 0
contributing/development.html 78 9.22 0
guide/dispatchers.html 31 9.77 1
reference/cli.html 23 8.78 0

The pages rank but don't get clicks. mdBook uses the SUMMARY.md entry as the <title> tag - generic titles like 'Control Plane - Barbacane Documentation' don't sell the page in the SERP. New titles lead with the function ('Control plane (REST API)', 'WASM plugin development') so the SERP snippet is more clickable.

The AWX/Makefile noise was a single GSC query ('running the ui development' awx or makefile) at position 1 with 31 impressions and 0 clicks - users searching for AWX docs were getting our page instead. Rephrasing breaks the exact-phrase match.

Test plan

  • Run mdbook build locally and verify the rendered <title> tag on the touched pages
  • Confirm the sidebar still reads cleanly (longer entries should still wrap fine)
  • After merge, request reindex in Search Console for the changed URLs

- SUMMARY.md and H1s reworded for the high-impression docs pages (control plane, middlewares, dispatchers, getting started, CLI reference, dev setup, plugin development, spec configuration); also moved to sentence case for those entries
- 'Running the UI' heading and surrounding parenthetical in control-plane.md rephrased to break the exact phrase 'running the UI development' that was attracting AWX/Makefile-related search traffic (31 impressions, 0 clicks at position 1 over the last 90 days)
@ndreno ndreno merged commit 157f6ce into main Apr 29, 2026
12 checks passed
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.

1 participant