Skip to content

Bring learners from search engines to the book and the repository #216

Closed

Description

@ShisatoYano

Part of #183.

Problem

Learners who search for an algorithm ("Stanley controller Python", "MPPI path tracking") should land on the book's page about it, and from there find the simulation and the repository. Today the web book has none of the basics that search engines and link previews use. Checked on the published pages:

  • No sitemap.xml, so new chapter pages are found late
  • No <meta name="description">, so search results show whatever text comes first on the page
  • No canonical URL, so a page and its Markdown file on GitHub can compete in search
  • No Open Graph tags, so a chapter shared on LinkedIn or X shows no image or summary
  • The site is not registered in Google Search Console, so we don't know which searches bring visitors

Expected change

1. Be found

  • Add sphinx-sitemap and set html_baseurl (this also gives every page a canonical URL)
  • Register the site in Google Search Console and submit the sitemap (the maintainer does this; it needs a verification file or meta tag in the book)
  • Give every chapter and section page a one-sentence description (MyST front matter), written with the words people search for (the algorithm's name and "Python")

2. From the book to the repository

  • Add sphinxext-opengraph, with the chapter's demo GIF or figure as the preview image where there is one
  • At the top of each section about an algorithm, link to its simulation: "Run it: python src/simulations/..." and the folder on GitHub
  • A small "Star the repository on GitHub" link in the sidebar or footer of every page

3. Measure

  • Record the top search queries and the clicks from Search Console with the monthly metrics (stars, GitHub traffic from Google), so we can see which pages bring learners

Done when

  • The published book has a sitemap, canonical URLs, descriptions and Open Graph tags on every page
  • The site is verified in Search Console and the sitemap is submitted
  • Each algorithm section links to its simulation

Activity

  1. ShisatoYano commented on Nov 8, 2026

    @ShisatoYano
    OwnerAuthor

    Done in #217 and #218:

    • Be found: the book publishes sitemap.xml (24 pages), and every page has a canonical URL, a description and Open Graph tags. The site is verified in Google Search Console, and the sitemap is submitted.
    • Search words: each page starts with a sentence that names the algorithm with the words learners search for ("explained", "equations", "Python", "A vs B"), and the writing guide asks new pages to do the same.
    • From the book to the repository: a "Star the repository on GitHub" link in the sidebar, and "Run it" lines under the algorithm demos (Stanley, MPC, MPPI). New sections get them from the template in the writing guide.
    • Measure: the top search queries and clicks from Search Console are recorded with the monthly metrics, once there is data (it takes a few days to weeks).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions