New [tool.repomatic] sphinx.builder config

Author: kdeldycke

.github/workflows/docs.yaml

@@ -63,7 +63,7 @@ jobs:
         run: >
           uv --no-progress run --frozen -- repomatic metadata
           --format github-json --output "$GITHUB_OUTPUT"
-          is_python_project is_sphinx doc_files
+          is_python_project is_sphinx doc_files sphinx_builder
 
   deploy-docs:
     name: 📖 Deploy Sphinx doc
@@ -104,7 +104,12 @@ jobs:
             fonts-liberation graphviz mandoc
       - name: Build documentation
         # Install --all-extras so documentation can covers all features of the project, including the optional ones.
-        run: uv --no-progress run --frozen --all-extras --group docs -- sphinx-build -b html ./docs ./docs/_build
+        # The builder is `[tool.repomatic] sphinx.builder`, defaulting to `html`:
+        # a project serving extension-less URLs sets it to `dirhtml`.
+        run: >
+          uv --no-progress run --frozen --all-extras --group docs --
+          sphinx-build -b ${{ fromJSON(needs.metadata.outputs.metadata).sphinx_builder }}
+          ./docs ./docs/_build
       - name: Upload artifact
         uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:

changelog.md

@@ -5,6 +5,8 @@
 > [!WARNING]
 > This version is **not released yet** and is under active development.
 
+- New `[tool.repomatic] sphinx.builder` config choosing the Sphinx builder the Docs workflow deploys, so a project can publish extension-less URLs with `dirhtml`.
+
 ## [`7.12.0` (2026-08-14)](https://github.com/kdeldycke/repomatic/compare/v7.11.0...v7.12.0)
 
 - New `ci-status` command reporting each workflow's latest run and which of its failing jobs gate a merge, read from jobs rather than run conclusions.

repomatic/config.py

@@ -1066,6 +1066,25 @@ class Config:
     enablement keys it owns into whatever the file already holds.
     """
 
+    sphinx_builder: str = field(
+        default="html",
+        metadata={CONFIG_PATH_METADATA_KEY: "sphinx.builder"},
+    )
+    """Sphinx builder producing the deployed documentation site.
+
+    The default `html` writes `page.html`, so the site serves `/page.html`.
+    Setting it to `dirhtml` writes `page/index.html` instead, so the same page
+    serves at `/page/` and the published URLs carry no extension, which is the
+    shape search engines and most static hosts expect.
+
+    The one Sphinx setting a project cannot make in its own `conf.py`, hence a
+    config key: the builder is chosen on the command line, and `docs.yaml` is
+    what runs it. Switching an already-published site republishes every URL it
+    has: the old paths stop existing, so the repository's own absolute
+    self-links (readme, packaging specs) move in the same commit, and whatever
+    fronts the site redirects the old ones.
+    """
+
     test_matrix: TestMatrixConfig = field(
         default_factory=TestMatrixConfig,
         metadata={

tests/test_metadata.py

@@ -845,6 +845,8 @@ def _tracked_inventory(
     "major_bump_allowed": AnyBool(),
     # `minimum-release-age` default "1 week", rendered as whole days for npm.
     "npm_min_release_age_days": 7,
+    # This repository publishes `.html` pages, the `sphinx.builder` default.
+    "sphinx_builder": "html",
 }