Skip to content

fix: sitemap config #477

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
minaelee merged 2 commits into from
Dec 10, 2025
Merged

fix: sitemap config #477

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f3888b8
fix: remove redundancy in sitemap_url_scheme
minaelee Dec 4, 2025
15b0b3d
doc: update sitemaps how-to guide and changelog
minaelee Dec 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@
## 1.4.0

* Switches doc links to `stable` slug.
* !!POTENTIAL BREAKING CHANGE: Fixes duplicate version strings in sitemaps for versioned docs. This removes the `version` variable previously set in the sitemaps configuration section of `conf.py`. If you have any custom code that uses this variable elsewhere, do not remove it.

### Changed

* `docs/conf.py` [#477](https://github.com/canonical/sphinx-docs-starter-pack/pull/477)
* `docs/Makefile` [#468](https://github.com/canonical/sphinx-docs-starter-pack/pull/468), [#472](https://github.com/canonical/sphinx-docs-starter-pack/pull/472)
* `.github/workflows/automatic-doc-checks.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466)
* `.github/workflows/check-removed-urls.yml` [#466](https://github.com/canonical/sphinx-docs-starter-pack/pull/466)
Expand Down
11 changes: 3 additions & 8 deletions docs/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -186,14 +186,9 @@

html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")

# URL scheme. Add language and version scheme elements.
# When configured with RTD variables, check for RTD environment so manual runs succeed:

if 'READTHEDOCS_VERSION' in os.environ:
version = os.environ["READTHEDOCS_VERSION"]
sitemap_url_scheme = '{version}{link}'
else:
sitemap_url_scheme = 'MANUAL/{link}'
# sphinx-sitemap uses html_baseurl to generate the full URL for each page:

sitemap_url_scheme = '{link}'

# Include `lastmod` dates in the sitemap:

Expand Down
55 changes: 13 additions & 42 deletions docs/how-to/set-up-sitemaps.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,55 +31,26 @@ Add ``sphinx_sitemap`` to ``extensions`` in your configuration file (:file:`docs

extensions = ['sphinx_sitemap']

Required sitemap configuration
------------------------------

Sphinx Sitemap requires a ``html_baseurl`` configured for the project in your
configuration file. For example, in :file:`docs/conf.py`:

.. code-block::

html_baseurl = 'https://canonical-starter-pack.readthedocs-hosted.com/'

Make sure to include the trailing slash (``/``) to avoid errors in the concatenated
URLs in the sitemap.

.. note::

Sitemap configuration is included in the Starter pack's
`default configuration file <https://github.com/canonical/sphinx-docs-starter-pack/blob/a489ae041f6cebb7948fdf21b996e8c67d636a83/docs/conf.py#L176>`_.

URL configuration
-----------------

Sphinx sitemap uses a configurable URL scheme to set language and version options
for your documentation. If you have no languages and no versions in your URL, add
the following to your ``conf.py`` file:

.. code-block::

sitemap_url_scheme = "{link}"
Sitemap configuration
---------------------

To add versioning, this can be done manually, or you can read the version from
the RTD instance. To implement a manual version:
The Sphinx starter pack's configuration file (:file:`docs/conf.py`) includes default sitemap configuration.

.. code-block::
The ``sphinx-sitemap`` extension requires a ``html_baseurl`` variable to be configured.
This is set as follows:

sitemap_url_scheme = "<version>/{link}"
.. code-block:: python

Or, if the version is set with the ``version`` key in your configuration file:
html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "/")

.. code-block::
When building on Read the Docs, this sets ``html_baseurl`` dynamically to the value of the
``READTHEDOCS_CANONICAL_URL`` environment variable, which resolves to the full URL of the documentation
including the version and language (if applicable).

sitemap_url_scheme = "{version}{link}"
In local builds and builds on other hosts, ``html_baseurl`` defaults to ``/``.

To read from the provided RTD environment variable::

if 'READTHEDOCS_VERSION' in os.environ:
version = os.environ["READTHEDOCS_VERSION"]
sitemap_url_scheme = '{version}{link}'
else:
sitemap_url_scheme = 'MANUAL/{link}'
The ``sitemap_url_scheme`` variable is set to ``'{link}'`` by default. This uses the value of ``html_baseurl`` to generate
the full URL for each page for the sitemap.

.. note::

Expand Down
Loading