kattni · Feb 26, 2026 · Feb 2, 2026 · Feb 2, 2026 · Feb 2, 2026 · Feb 26, 2026
diff --git a/changes/2665.misc.md b/changes/2665.misc.md
@@ -0,0 +1 @@
+ Documentation build configuration is now updated to work with the updated tooling.
diff --git a/docs/config.yml b/docs/config.yml
@@ -32,6 +32,7 @@ extra:
   "ci_tested": ●
   "maintainer_tested": ○
   "not_tested": △
+  generator: false
 
 extra_css:
   - stylesheets/briefcase.css
@@ -44,6 +45,8 @@ theme:
   features:
     - content.tabs.link
     - toc.follow
+    - navigation.tabs
+    - navigation.tabs.sticky
     - navigation.indexes
     - navigation.footer
     - search.suggest
@@ -72,21 +75,58 @@ theme:
         name: Switch to system preference
 
 markdown_extensions:
+  # PyMdown Extensions
   pymdownx.highlight: {}
   pymdownx.superfences: {}
-  pymdownx.blocks.admonition: {}
   pymdownx.blocks.caption: {}
-  pymdownx.details: {}
+  pymdownx.blocks.admonition:  # Enables admonitions.
+    types:
+      - note
+      - abstract
+      - info
+      - tip
+      - success
+      - question
+      - warning
+      - failure
+      - danger
+      - bug
+      - example
+      - quote
+  pymdownx.blocks.details:  # Enables collapsible content.
+    types:
+      - {name: details-note, class: note}
+      - {name: details-abstract, class: abstract}
+      - {name: details-info, class: info}
+      - {name: details-tip, class: tip}
+      - {name: details-success, class: success}
+      - {name: details-question, class: question}
+      - {name: details-warning, class: warning}
+      - {name: details-failure, class: failure}
+      - {name: details-danger, class: danger}
+      - {name: details-bug, class: bug}
+      - {name: details-example, class: example}
+      - {name: details-quote, class: quote}
   pymdownx.blocks.tab:
     alternate_style: true
+  pymdownx.magiclink:  # Among other things, enables GitHub shorthand references.
+    provider: "github"
+    user: "beeware"
+    repo: "toga"
+    repo_url_shortener: true
+    repo_url_shorthand: true
+    normalize_issue_symbols: true
   pymdownx.snippets:
     base_path: ["docs/en"]
     url_download: true
     check_paths: true
+  # Python Markdown Extensions
+  attr_list: {}
+  smarty:  # Enables easy em and en dashes.
+    smart_quotes: false
   toc:
     permalink: true
     title: On this page
-  attr_list: {}
 
 plugins:
   search: {}

diff --git a/docs/mkdocs.en.yml b/docs/mkdocs.en.yml
@@ -5,3 +5,6 @@ docs_dir: en
 
 theme:
   language: en
+
+extra:
+  header: {}
diff --git a/pyproject.toml b/pyproject.toml
@@ -103,7 +103,7 @@ setuptools-scm = [
 ]
 
 towncrier = [
-    "towncrier==25.8.0",
+    "towncrier == 25.8.0",
 ]
 
 tox-uv = [

diff --git a/tox.ini b/tox.ini
@@ -98,6 +98,6 @@ commands =
     !lint-!all-!live-!en : build_md_translations {posargs} en
     lint : pyspelling
     lint : markdown-checker --dir {[docs]docs_dir} --func check_broken_urls --skip-domains=https://www.firegiant.com,https://flathub.org,https://wunjo.online,https://www.x.org
-    live : live_serve_en {posargs}
+    live : live_serve_en {posargs} --port=8039
     all : build_md_translations {posargs} en
     en : build_md_translations {posargs} en
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		Documentation build configuration is now updated to work with the updated tooling.
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,3 +5,6 @@ docs_dir: en @@
     theme:
       language: en
+    extra:
+      header: {}