git-pull · tony · Apr 25, 2026 · Apr 21, 2026 · Apr 21, 2026 · Apr 21, 2026
diff --git a/CHANGES b/CHANGES
diff --git a/docs/_ext/package_reference.py b/docs/_ext/package_reference.py
diff --git a/docs/api.md b/docs/api.md
@@ -10,6 +10,11 @@ For shared defaults and configuration options, see {doc}`configuration`.
 .. autofunction:: gp_sphinx.config.merge_sphinx_config
 ```
 
+When `docs_url` is provided, `merge_sphinx_config()` also auto-derives
+the `ogp_*` and `sitemap_*` keys consumed by the SEO extensions
+(`sphinx_gp_opengraph`, `sphinx_gp_sitemap`). See {ref}`from-docs_url` for the full
+mapping.
+
 ## make_linkcode_resolve
 
 ```{eval-rst}

diff --git a/docs/configuration.md b/docs/configuration.md
@@ -41,7 +41,7 @@ All parameters are keyword-only.
 | `source_branch` | `str` | `"main"` | Source branch stored in `html_theme_options["source_branch"]` |
 | `light_logo` | `str \| None` | `None` | Light-mode logo path merged into theme options |
 | `dark_logo` | `str \| None` | `None` | Dark-mode logo path merged into theme options |
-| `docs_url` | `str \| None` | `None` | Canonical docs URL used to derive Open Graph settings |
+| `docs_url` | `str \| None` | `None` | Canonical docs URL. When set, auto-derives `ogp_site_url`, `ogp_site_name`, `ogp_image` (for `sphinx_gp_opengraph`) and `site_url`, `sitemap_url_scheme` (for `sphinx_gp_sitemap`) — see {ref}`from-docs_url` |
 | `intersphinx_mapping` | `Mapping[str, tuple[str, str \| None]] \| None` | `None` | Mapping assigned to `intersphinx_mapping` when provided |
 | `**overrides` | `Any` | none | Final escape hatch for any Sphinx config key; applied after all defaults and auto-computed values |
 
@@ -55,13 +55,24 @@ All parameters are keyword-only.
 | `html_theme_options["source_repository"]` | repository URL |
 | `html_theme_options["footer_icons"][0]["url"]` | repository URL for the GitHub footer icon |
 
+(from-docs_url)=
+
 ### From `docs_url`
 
 | Key | Value |
 | --- | --- |
-| `ogp_site_url` | `docs_url` |
+| `ogp_site_url` | `docs_url` (trailing-slash normalized) |
 | `ogp_site_name` | `project` |
 | `ogp_image` | `"_static/img/icons/icon-192x192.png"` |
+| `site_url` | `docs_url` (trailing-slash normalized) |
+| `sitemap_url_scheme` | `"{link}"` |
+
+`sitemap_url_scheme` overrides upstream sphinx-sitemap's default of
+`"{lang}{version}{link}"` because git-pull.com sites deploy flat at the
+project root with no language or version path segment. Multilingual or
+version-pinned hosting can pass an explicit `sitemap_url_scheme` to
+`merge_sphinx_config()` to restore the prefixed scheme — `**overrides`
+is applied after auto-computation, so the explicit value wins.
 
 ### From `**overrides`
 
@@ -100,7 +111,7 @@ These are injected even though they are not exposed as `DEFAULT_*` constants:
 
 | Constant | Value |
 | --- | --- |
-| `DEFAULT_EXTENSIONS` | `["sphinx.ext.autodoc", "sphinx_fonts", "sphinx.ext.intersphinx", "sphinx_autodoc_typehints_gp", "sphinx.ext.todo", "sphinx_inline_tabs", "sphinx_copybutton", "sphinxext.opengraph", "sphinxext.rediraffe", "sphinx_design", "myst_parser", "linkify_issues"]` |
+| `DEFAULT_EXTENSIONS` | `["sphinx.ext.autodoc", "sphinx_fonts", "sphinx.ext.intersphinx", "sphinx_autodoc_typehints_gp", "sphinx.ext.todo", "sphinx_inline_tabs", "sphinx_copybutton", "sphinx_gp_opengraph", "sphinx_gp_sitemap", "sphinxext.rediraffe", "sphinx_design", "myst_parser", "linkify_issues"]` |
 | `DEFAULT_SOURCE_SUFFIX` | `{".rst": "restructuredtext", ".md": "markdown"}` |
 | `DEFAULT_MYST_EXTENSIONS` | `["colon_fence", "substitution", "replacements", "strikethrough", "linkify"]` |
 | `DEFAULT_MYST_HEADING_ANCHORS` | `4` |

diff --git a/docs/index.md b/docs/index.md
@@ -133,3 +133,11 @@ packages/sphinx-autodoc-typehints-gp
 packages/gp-sphinx
 packages/sphinx-gp-theme
 ```
+
+```{toctree}
+:caption: SEO
+:hidden:
+
+packages/sphinx-gp-opengraph
+packages/sphinx-gp-sitemap
+```
diff --git a/docs/packages/gp-sphinx.md b/docs/packages/gp-sphinx.md
@@ -48,12 +48,23 @@ globals().update(conf)
 ## What it injects
 
 - Shared extension defaults, theme defaults, fonts, MyST, napoleon, copybutton, and rediraffe settings.
-- Auto-computed values like `issue_url_tpl`, `ogp_site_url`, `ogp_site_name`, and `ogp_image` when repository and docs URLs are provided.
+- Auto-computed `issue_url_tpl` and theme source-repository wiring from `source_repository`.
+- Auto-computed SEO values when `docs_url` is set: `ogp_site_url`, `ogp_site_name`, `ogp_image` for {doc}`sphinx-gp-opengraph`, plus `site_url` and `sitemap_url_scheme` for {doc}`sphinx-gp-sitemap`. See {ref}`from-docs_url` for the canonical mapping.
 - A `setup(app)` hook that registers `js/spa-nav.js` and removes `tabs.js` after HTML builds.
 - Support for appending {py:mod}`sphinx:sphinx.ext.linkcode` automatically when `linkcode_resolve` is supplied in `**overrides`.
 
 See {doc}`/configuration` for the complete parameter reference and every shared `DEFAULT_*` constant.
 
+## SEO emission for free
+
+`sphinx_gp_opengraph` and `sphinx_gp_sitemap` are members of
+{py:data}`~gp_sphinx.defaults.DEFAULT_EXTENSIONS`, so every project
+that calls `merge_sphinx_config()` loads them automatically. Passing
+`docs_url=` is the only step required for default SEO emission —
+gp-sphinx fills in the upstream config keys both extensions need.
+Per-package details live on the {doc}`sphinx-gp-opengraph` and
+{doc}`sphinx-gp-sitemap` pages.
+
 :::{admonition} Live example
 This site is built with `gp-sphinx`, using the same integration pattern shown
 above. See

diff --git a/docs/packages/index.md b/docs/packages/index.md
@@ -1,6 +1,6 @@
 # Packages
 
-Twelve workspace packages in three tiers.
+Fourteen workspace packages in four tiers.
 
 **Shared infrastructure** — the rendering pipeline that all domain packages consume:
 - `sphinx-ux-badges` — badge primitives and colour palette
@@ -18,6 +18,10 @@ directives, roles, and per-domain indices:
 assets:
 - `gp-sphinx`, `sphinx-gp-theme`, `sphinx-fonts`
 
+**SEO** — meta-tag and crawlability extensions auto-loaded by
+`gp-sphinx` when `docs_url` is set:
+- `sphinx-gp-opengraph`, `sphinx-gp-sitemap`
+
 `gp-sphinx` is the umbrella entry point: `merge_sphinx_config()` wires up the
 full stack for downstream projects.
 

diff --git a/docs/packages/sphinx-autodoc-fastmcp.md b/docs/packages/sphinx-autodoc-fastmcp.md
@@ -178,6 +178,34 @@ for a plain inline reference.
 .. fastmcp-tool-summary::
 ```
 
+## Config reference
+
+Generated from `app.add_config_value()` registrations in
+[`sphinx_autodoc_fastmcp/__init__.py`](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-autodoc-fastmcp/src/sphinx_autodoc_fastmcp/__init__.py).
+
+```{eval-rst}
+.. autoconfigvalue-index:: sphinx_autodoc_fastmcp
+.. autoconfigvalues:: sphinx_autodoc_fastmcp
+```
+
+## Directive and role reference
+
+Generated from `app.add_directive()` and `app.add_role()` registrations in
+[`sphinx_autodoc_fastmcp/__init__.py`](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-autodoc-fastmcp/src/sphinx_autodoc_fastmcp/__init__.py)
+via `sphinx-autodoc-docutils`. The summary tables index every entry;
+the descriptor blocks below carry the per-item signature, badges, and
+options.
+
+```{eval-rst}
+.. autodirective-index:: sphinx_autodoc_fastmcp
+
+.. autorole-index:: sphinx_autodoc_fastmcp
+
+.. autodirectives:: sphinx_autodoc_fastmcp
+
+.. autoroles:: sphinx_autodoc_fastmcp
+```
+
 ## Package reference
 
 ```{package-reference} sphinx-autodoc-fastmcp

diff --git a/docs/packages/sphinx-autodoc-sphinx.md b/docs/packages/sphinx-autodoc-sphinx.md
@@ -80,16 +80,22 @@ Renders all config values from a module at once:
 .. autoconfigvalues:: sphinx_config_demo
 ```
 
-### Document the extension's own directive helper
+## Directive reference
+
+Generated from `app.add_directive()` registrations in
+[`sphinx_autodoc_sphinx/__init__.py`](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-autodoc-sphinx/src/sphinx_autodoc_sphinx/__init__.py)
+via `sphinx-autodoc-docutils` — a meta-loop where the package that
+documents config values uses its sibling package to document its own
+directives. The summary table indexes every directive; the descriptor
+blocks below carry the per-item signature, badge, and options.
 
 ```{eval-rst}
-.. autodirective:: sphinx_autodoc_sphinx._directives.AutoconfigvalueDirective
-   :no-index:
+.. autodirective-index:: sphinx_autodoc_sphinx
+
+.. autodirectives:: sphinx_autodoc_sphinx
 ```
 
-The extension itself registers documentation directives rather than new roles
-or config values. The generated package reference below lists its registered
-surface from the live `setup()` calls.
+## Package reference
 
 ```{package-reference} sphinx-autodoc-sphinx
 ```

diff --git a/docs/packages/sphinx-gp-opengraph.md b/docs/packages/sphinx-gp-opengraph.md
@@ -0,0 +1,117 @@
+(sphinx-gp-opengraph)=
+
+# sphinx-gp-opengraph
+
+```{gp-sphinx-package-meta} sphinx-gp-opengraph
+```
+
+:::{admonition} Alpha
+:class: warning
+
+Rendered output is stable. The Python API and Sphinx config value names
+may change without a major version bump. Pin your dependency to a
+specific version range in production.
+:::
+
+OpenGraph meta-tag emission for Sphinx. The package registers every
+`ogp_*` config value the upstream
+[`sphinxext-opengraph`](https://github.com/sphinx-doc/sphinxext-opengraph)
+exposes and emits the same `<meta>` tags, with one deliberate
+omission: the matplotlib-based social-card generator is not bundled.
+That is why the package has zero non-Sphinx runtime dependencies.
+
+For install, per-page overrides, Twitter-card markup, and the
+verbatim deprecation-warning text, see the package
+[README](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-opengraph#readme).
+This page covers integration with gp-sphinx, the emission pipeline,
+the trade-offs, and the auto-generated config-value reference.
+
+## Integration with gp-sphinx
+
+`sphinx_gp_opengraph` ships in {py:data}`~gp_sphinx.defaults.DEFAULT_EXTENSIONS`,
+so projects that build through {py:func}`~gp_sphinx.config.merge_sphinx_config`
+load it automatically. Passing `docs_url=` to that function auto-derives
+three of the most common config values:
+
+| Auto-derived | Source |
+| --- | --- |
+| `ogp_site_url` | `docs_url` |
+| `ogp_site_name` | `project` |
+| `ogp_image` | `"_static/img/icons/icon-192x192.png"` |
+
+The canonical reference for these and the other auto-derived values
+lives in {ref}`from-docs_url`. Any value passed via `**overrides` to
+`merge_sphinx_config()` wins over the auto-derived default —
+auto-computation runs first, overrides apply last.
+
+## How the page-level meta tags are built
+
+For every page rendered by an HTML-family builder, the extension's
+`html-page-context` handler walks the resolved doctree and emits the
+following tags into `context["metatags"]`. The page is skipped when its
+front-matter sets `ogp_disable: true`.
+
+| Tag | Source |
+| --- | --- |
+| `og:title` | First heading of the page, with HTML stripped (`_title.py`) |
+| `og:type` | `ogp_type` (default `"website"`) |
+| `og:url` | `ogp_canonical_url or ogp_site_url`, joined with the page's relative URL |
+| `og:site_name` | `ogp_site_name`, or `project` when unset; suppressed when set to `False` |
+| `og:description` | First non-title body paragraph, truncated to `ogp_description_length`, HTML-escaped (`_description.py`) |
+| `og:image` | Page front-matter `og:image`, else `ogp_image`, else first in-page image when `ogp_use_first_image=True` |
+| `og:image:alt` | Front-matter `og:image:alt`, else `ogp_image_alt`, falling back to site name, then page title |
+| `<meta name="description">` | Mirror of `og:description` when `ogp_enable_meta_description=True` and the page does not already define one (`_meta.py`) |
+
+The description extractor walks the document, skips title nodes and
+empty paragraphs, takes the first prose paragraph, and truncates at the
+configured cap. Embedded HTML quote characters are escaped with
+`&quot;` before emission, so user content cannot break out of the
+attribute value.
+
+Custom raw markup listed in `ogp_custom_meta_tags` is appended verbatim
+after the structured tags — that is the supported escape hatch for
+Twitter card declarations and `og:image:width`/`og:image:height` hints.
+
+## Event hooks
+
+```text
+config-inited     →  _warn_if_social_cards_used     (deprecation warning)
+html-page-context →  html_page_context              (per-page meta-tag emission)
+```
+
+Both hooks live in
+[`sphinx_gp_opengraph/__init__.py`](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-opengraph/src/sphinx_gp_opengraph/__init__.py).
+There is no `builder-inited` or `build-finished` work — the extension
+is purely a per-page transformer.
+
+## Trade-offs
+
+**`ogp_social_cards` is accepted but ignored.** The upstream extension
+ships a matplotlib renderer that builds per-page PNGs at
+`builder-inited`. sphinx-gp-opengraph deliberately omits the dependency to
+keep the install graph small. The config key remains registered so
+existing `conf.py` files do not error; setting it logs a single
+`WARNING` at `config-inited` directing users to the static-image
+workflow documented in the README.
+
+**`parallel_read_safe` and `parallel_write_safe` are both `True`.**
+The extension never writes shared state — every emission is
+self-contained inside the per-page hook — so it is safe under any
+`sphinx-build -j N` value.
+
+## Config reference
+
+Generated from `app.add_config_value()` registrations in
+[`sphinx_gp_opengraph/__init__.py`](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-opengraph/src/sphinx_gp_opengraph/__init__.py).
+
+```{eval-rst}
+.. autoconfigvalue-index:: sphinx_gp_opengraph
+.. autoconfigvalues:: sphinx_gp_opengraph
+```
+
+## Package reference
+
+```{package-reference} sphinx-gp-opengraph
+```
+
+[Source on GitHub](https://github.com/git-pull/gp-sphinx/tree/main/packages/sphinx-gp-opengraph) · [PyPI](https://pypi.org/project/sphinx-gp-opengraph/)