Skip to content

SEO: per-page meta descriptions, social cards plugin, and slimmer crawl surface for the docs site #482

Description

@hexsecs

Problem

  • mkdocs-material reuses the global site_description ("CLI-first CAN security research toolkit documentation") as the meta description for every page unless the page sets description: front matter. Right now ~100 pages ship identical meta descriptions.
  • The cookbook/tutorial titles ("Decode SPN 110", "Fuzz Tesla DI_torque2 vehicle speed", "Verify a PCAN interface in 30 seconds") match real search queries almost verbatim — these are the project's best long-tail search assets and deserve individual descriptions.
  • ~70 nav pages are internal design/test specs, which dilutes what search engines see as the site's focus.
  • No per-page OG images for docs pages.

Suggested fix

  • Add description: front matter to the high-value pages: getting_started.md, feature-matrix.md, event-schema.md, security-use-cases.md, every cookbook/*.md, every tutorials/*.md (~30 pages)
  • Enable the built-in social plugin in mkdocs.yml (free in mkdocs-material; needs the cairo image deps in the docs CI job) to auto-generate OG card images per docs page
  • Consider excluding design/ and tests/ spec pages from the sitemap/index (e.g. mkdocs-exclude-search or a robots meta via template override), or grouping them behind a single "Internals" entry — keep them public, just de-emphasized

Acceptance criteria

High-value docs pages have unique meta descriptions; sharing a docs URL produces a per-page social card; the sitemap emphasizes user-facing pages.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions