{"id":6246,"library":"sphinx-sitemap","title":"Sphinx Sitemap Generator Extension","description":"Sphinx-sitemap is a Sphinx extension designed to automatically generate sitemaps.org compliant XML sitemaps for the HTML version of your Sphinx documentation. It supports multi-version and multi-language documentation, enhances SEO, and can include 'last modified' timestamps. The current version is 2.9.0, released on October 5, 2025.","status":"active","version":"2.9.0","language":"en","source_language":"en","source_url":"https://github.com/jdillard/sphinx-sitemap","tags":["Sphinx","documentation","sitemap","SEO","extension","Python"],"install":[{"cmd":"pip install sphinx-sitemap","lang":"bash","label":"Install via pip"}],"dependencies":[{"reason":"Core dependency as it's a Sphinx extension.","package":"Sphinx"}],"imports":[{"note":"Add 'sphinx_sitemap' to the `extensions` list in your `conf.py`.","symbol":"sphinx_sitemap","correct":"extensions = ['sphinx_sitemap']"}],"quickstart":{"code":"# In conf.py, typically located in your Sphinx project's root directory\n\nimport os\n\nproject = 'My Awesome Docs'\ncopyright = '2026, Your Name'\n\nextensions = [\n    'sphinx.ext.autodoc',\n    'sphinx.ext.napoleon',\n    'sphinx_sitemap',  # Add this line to enable the extension\n]\n\n# *** ESSENTIAL for sitemap generation ***\n# Set the base URL of your published documentation. This is critical for sitemap validity.\nhtml_baseurl = os.environ.get('DOCS_BASE_URL', 'https://example.com/docs/')\n\n# Optional: Enable 'lastmod' timestamps (requires Git repository with history)\n# sitemap_show_lastmod = True\n\n# Optional: Exclude specific pages or patterns from the sitemap\n# sitemap_exclude_pages = ['excluded_page.html', '**/private/*']\n\n# To generate the sitemap, navigate to your docs directory and run:\n# sphinx-build -b html . _build\n# The sitemap.xml will be generated in the _build directory.","lang":"python","description":"To get started, install the library and then enable the extension by adding 'sphinx_sitemap' to the `extensions` list in your Sphinx `conf.py`. Crucially, set the `html_baseurl` configuration variable to the root URL where your documentation will be hosted for correct sitemap generation."},"warnings":[{"fix":"Upgrade `sphinx-sitemap` to version 2.9.0 or newer: `pip install --upgrade sphinx-sitemap`. If an upgrade is not possible, pin Sphinx to a version `< 7.2.0`.","message":"Older versions of `sphinx-sitemap` (prior to 2.9.0, specifically versions before 2.8.0) experienced compatibility issues with Sphinx 7.2.x due to internal API changes within Sphinx (e.g., TocTree refactoring, `pathlib.Path` objects, and changes to JS/CSS handling). Ensure you are using `sphinx-sitemap` 2.9.0 or newer if targeting Sphinx 7.2.x or later.","severity":"breaking","affected_versions":"< 2.9.0 with Sphinx >= 7.2.0"},{"fix":"Always set `html_baseurl = 'https://your-docs-domain.com/path/'` in your `conf.py`. Ensure it accurately reflects the live URL of your documentation.","message":"The `html_baseurl` configuration variable in `conf.py` is absolutely critical for `sphinx-sitemap` to generate valid, absolute URLs in your `sitemap.xml`. If this variable is not set or contains an incorrect URL, the generated sitemap will be ineffective for search engines.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer to the `sphinx-sitemap` documentation on 'Versioning Configuration' and 'Multilingual Configuration' for detailed instructions on creating a `sitemapindex.xml`.","message":"For multi-version or multi-language Sphinx projects, `sphinx-sitemap` generates a separate sitemap for each version/language. You must then manually create a `sitemapindex.xml` file that links to these individual sitemaps to properly inform search engines of all available content.","severity":"gotcha","affected_versions":"All versions"},{"fix":"In CI/CD pipelines, configure Git to perform a full clone (e.g., `fetch-depth: 0` for GitHub Actions) rather than a shallow clone if you intend to use `sitemap_show_lastmod`.","message":"When `sitemap_show_lastmod = True` is enabled, the extension attempts to add `<lastmod>` timestamps based on Git's last update time for each page. This feature requires a full Git repository history to be available. Shallow clones, which are the default behavior in many Continuous Integration (CI) environments (e.g., GitHub Actions), are not supported and will result in the omission of `<lastmod>` tags.","severity":"gotcha","affected_versions":"All versions where `sitemap_show_lastmod` is used"},{"fix":"Set `sitemap_url_scheme` in your `conf.py` to match your desired URL structure (e.g., `sitemap_url_scheme = \"{link}\"` for no language/version prefix).","message":"As of Sphinx version 5, the `language` configuration value defaults to 'en'. This can affect the default URL scheme generated by `sphinx-sitemap`. If the default `{lang}{version}{link}` scheme produces incorrect URLs, particularly in multi-language setups, you may need to explicitly customize `sitemap_url_scheme`.","severity":"gotcha","affected_versions":"Sphinx >= 5 with `sphinx-sitemap`"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}