This release is a pre-release and may not be stable for production use.
sphinx-gp-sitemap
Sitemap generator for Sphinx — a drop-in replacement for
sphinx-sitemap updated
to Sphinx 8.1+ idioms. Same sitemap_* configuration surface, no
multiprocessing.Queue, and a soft (lazy-loaded) dependency on
sphinx-last-updated-by-git
that activates only when sitemap_show_lastmod = True.
Part of the gp-sphinx documentation platform.
Install
$ pip install sphinx-gp-sitemap
When you depend on gp-sphinx, this extension is already loaded — see
Auto-derived values
below. The full config-key reference is auto-generated on the
package docs page
from the live app.add_config_value() registrations.
Minimum viable conf.py
extensions = [
"sphinx_gp_sitemap",
]
site_url = "https://example.com/"
After every HTML-family build, sitemap.xml is written to the output
directory. One <url> element per page; the index of the dirhtml
builder is emitted as the bare base URL (not index/). When
site_url is unset and html_baseurl is also unset, sitemap
emission is skipped silently — the notice is logged at INFO, not
WARNING, so -W strict builds do not fail on undeployed projects.
Auto-derived values when used with gp-sphinx
Projects that build through {py:func}gp_sphinx.config.merge_sphinx_config
do not need to set site_url or sitemap_url_scheme manually. Pass
docs_url= to merge_sphinx_config() and gp-sphinx fills both:
site_urlis normalized to end in/.sitemap_url_schemeis set to"{link}"— flat, no language or version path segment — because git-pull.com sites deploy at the project root.
See the sphinx-gp-sitemap package
page for the integration story
and configuration.md
for the canonical mapping table.
Builder support
| Builder | URL shape | Notes |
|---|---|---|
html |
…/<page>.html (or …<html_file_suffix>) |
Honors html_file_suffix for .htm mirrors |
dirhtml |
…/<page>/ |
Site index emitted as the bare site_url, not …/index/ |
Other builders (text, latex, singlehtml, …) are unaffected — they
do not fire html-page-context, so no sitemap is written.
Multi-language sites
When sitemap_locales is set or auto-detected from locale_dirs,
each <url> gains <xhtml:link rel="alternate" hreflang="…">
entries for every locale. Underscores in locale codes are rewritten
to hyphens for IANA compatibility (pt_BR → pt-BR).
sitemap_locales = ["de", "fr", "ja"]
Use sitemap_locales = [None] to explicitly suppress hreflang
alternates — useful when locale_dirs is populated for translation
workflows that do not produce hreflang-eligible deploys.
Excluding pages
sitemap_excludes = [
"draft/*",
"internal-*",
]
Patterns match the sitemap_link (the relative page URL after the
builder applies its suffix) via fnmatch. The patterns run after
suffix application, so draft/index.html and draft/index/ both
match draft/* regardless of builder.
lastmod from git
sitemap_show_lastmod = True
The first time config-inited fires with this flag set, sphinx-gp-sitemap
runs app.setup_extension("sphinx_last_updated_by_git") to load
sphinx-last-updated-by-git
on demand. Per-page <lastmod> values come from each source file's
latest commit timestamp. If the supporting extension is not
installed, sphinx-gp-sitemap warns once and disables sitemap_show_lastmod
for the rest of the build — <lastmod> is simply omitted.
Differences from sphinx-sitemap
Configuration is drop-in compatible — every sitemap_* key is
registered with the same name, type, and default. Behaviourally the
package is the same except for one explicit trade-off:
- Parallel writes are not declared safe. Collected links live in
env.temp_data["sphinx_gp_sitemap_links"], which Sphinx documents as per-process state and does not merge acrosssphinx-build -j Nworkers. sphinx-gp-sitemap therefore advertisesparallel_read_safeonly. Sites that need parallel writes should run a separate non-parallel pass for sitemap generation, or upstream the env-merge work to this package.
The other differences are implementation modernizations (no
multiprocessing.Queue, public app.builder.name == "dirhtml"
detection rather than monkey-patching, contextlib.suppress(ExtensionError)
around the optional html_baseurl re-registration). These do not
change the configuration surface.
See also
- sphinx-gp-opengraph — companion package for OpenGraph meta-tag emission
- gp-sphinx — the umbrella
docs platform; auto-derives
site_urlandsitemap_url_schemefrom a singledocs_urlargument - sphinx-gp-sitemap package page — integration story, event hooks, and the parallel-write trade-off
1 maintainer
Metadata
1 maintainer
Release files for sphinx-gp-sitemap 0.1.0a39
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| sphinx_gp_sitemap-0.1.0a39.tar.gz | 10.0 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| sphinx_gp_sitemap-0.1.0a39-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 18.9 kB
Release files / sphinx_gp_sitemap-0.1.0a39.tar.gz
| Download URL | sphinx_gp_sitemap-0.1.0a39.tar.gz |
|---|---|
| Size | 10.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8e35f0e50b44d6e4c03138e7c0388104c25b10ac51fc5cac48752138e1d0123c
|
|
BLAKE2b-256 checksum How to use checksums |
3a3796ac86dae10acdd0d8bbe604eec7a0d162b8999d39cfe6733162b7aa928a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logRelease files / sphinx_gp_sitemap-0.1.0a39-py3-none-any.whl
| Download URL | sphinx_gp_sitemap-0.1.0a39-py3-none-any.whl |
|---|---|
| Size | 9.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8877c85962d9356e4d99150581fe36137f084cbafa5a8b571b9d798d05e86f9a
|
|
BLAKE2b-256 checksum How to use checksums |
6b4d52ca7dee2128d6c4a52d4afc8a8916651eb75580f5867e75aa3070642fbc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logSecurity for sphinx-gp-sitemap 0.1.0a39
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for sphinx_gp_sitemap-0.1.0a39.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 6, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
