beeware · freakboy3742 · Jun 4, 2026 · Jun 2, 2026 · Jun 2, 2026 · Jun 3, 2026
diff --git a/docs/config.yml b/docs/config.yml
@@ -22,6 +22,7 @@ extra:
   translated: true  # false hides content related to building translations. Default: false.
   hide_coverage: false  # true hides content related to code coverage. Default: false.
   macos_only: false  # true hides tabbed content, and displays only macOS instructions. Default: false.
+  contribution_guide_root: content_test_bed/how-to/contribute
   alternate:
     - name: English
       link: /en/

diff --git a/docs/en/content_test_bed/how-to/contribute/first-time-contributors.md b/docs/en/content_test_bed/how-to/contribute/first-time-contributors.md
@@ -1,3 +1,3 @@
 # First-time contributors
 
-{% extends "contribute/first-time-contributors.md" %}
+{% extends "_shared/contribute/first-time-contributors.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/branches.md b/docs/en/content_test_bed/how-to/contribute/how/branches.md
@@ -1,3 +1,3 @@
 # Work from a feature branch, not your `main` branch
 
-{% extends "contribute/how/branches.md" %}
+{% extends "_shared/contribute/how/branches.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/build-docs.md b/docs/en/content_test_bed/how-to/contribute/how/build-docs.md
@@ -1,15 +1,15 @@
 # Building documentation
 
-{% extends "contribute/how/build-docs.md" %}
+{% extends "_shared/contribute/how/build-docs.md" %}
 
 {% block front_matter %}
 
-Before you build the documentation, and have a [development environment](dev-environment.md) set up.
+Before you build the documentation, and have a [development environment](../how/dev-environment.md) set up.
 
 {% endblock %}
 
 {% block end_matter %}
 
-Once you have successfully built the docs, you are ready to [write documentation](write-docs.md).
+Once you have successfully built the docs, you are ready to [write documentation](../how/write-docs.md).
 
 {% endblock %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/change-note.md b/docs/en/content_test_bed/how-to/contribute/how/change-note.md
@@ -1,3 +1,3 @@
 # Adding change information for release notes
 
-{% extends "contribute/how/change-note.md" %}
+{% extends "_shared/contribute/how/change-note.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/dev-environment.md b/docs/en/content_test_bed/how-to/contribute/how/dev-environment.md
@@ -1,3 +1,3 @@
 # Setting up a development environment
 
-{% extends "contribute/how/dev-environment.md" %}
+{% extends "_shared/contribute/how/dev-environment.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/new-issue.md b/docs/en/content_test_bed/how-to/contribute/how/new-issue.md
@@ -1,3 +1,3 @@
 # Submitting a new issue
 
-{% extends "contribute/how/new-issue.md" %}
+{% extends "_shared/contribute/how/new-issue.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/propose-feature.md b/docs/en/content_test_bed/how-to/contribute/how/propose-feature.md
@@ -1,6 +1,6 @@
 # Proposing a new feature
 
-{% extends "contribute/how/propose-feature.md" %}
+{% extends "_shared/contribute/how/propose-feature.md" %}
 
 {% block end_matter %}
 

diff --git a/docs/en/content_test_bed/how-to/contribute/how/reproduce-issue.md b/docs/en/content_test_bed/how-to/contribute/how/reproduce-issue.md
@@ -1,10 +1,10 @@
 # Reproducing an issue
 
-{% extends "contribute/how/reproduce-issue.md" %}
+{% extends "_shared/contribute/how/reproduce-issue.md" %}
 
 {% block front_matter %}
 
-To begin reproducing an issue, you will need a [development environment](dev-environment.md) set up.
+To begin reproducing an issue, you will need a [development environment](../how/dev-environment.md) set up.
 
 {% endblock %}
 

diff --git a/docs/en/content_test_bed/how-to/contribute/how/review-pr.md b/docs/en/content_test_bed/how-to/contribute/how/review-pr.md
@@ -1,3 +1,3 @@
 # Providing a pull request review
 
-{% extends "contribute/how/review-pr.md" %}
+{% extends "_shared/contribute/how/review-pr.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/scope-creep.md b/docs/en/content_test_bed/how-to/contribute/how/scope-creep.md
@@ -1,3 +1,3 @@
 # Avoiding scope creep
 
-{% extends "contribute/how/scope-creep.md" %}
+{% extends "_shared/contribute/how/scope-creep.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/submit-pr.md b/docs/en/content_test_bed/how-to/contribute/how/submit-pr.md
@@ -1,16 +1,16 @@
 # Submitting a pull request
 
-{% extends "contribute/how/submit-pr.md" %}
+{% extends "_shared/contribute/how/submit-pr.md" %}
 
 {% block end_matter %}
 
 {% if config.extra.website %}
 
-Your pull request may require additional content, such as a [change note](change-note.md), before it can be [reviewed](../next/pr-review.md).
+Your pull request may require additional content, such as a [change note](../how/change-note.md), before it can be [reviewed](../next/pr-review.md).
 
 {% else %}
 
-As part of submitting a pull request, you'll need to include a [change note](change-note.md) before it can be [reviewed](../next/pr-review.md).
+As part of submitting a pull request, you'll need to include a [change note](../how/change-note.md) before it can be [reviewed](../next/pr-review.md).
 
 {% endif %}
 

diff --git a/docs/en/content_test_bed/how-to/contribute/how/translate.md b/docs/en/content_test_bed/how-to/contribute/how/translate.md
@@ -1,3 +1,3 @@
 # Translating content
 
-{% extends "contribute/how/translate.md" %}
+{% extends "_shared/contribute/how/translate.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/write-code.md b/docs/en/content_test_bed/how-to/contribute/how/write-code.md
@@ -1,15 +1,15 @@
 # Writing, running, and testing code
 
-{% extends "contribute/how/write-code.md" %}
+{% extends "_shared/contribute/how/write-code.md" %}
 
 {% block front_matter %}
 
-To begin working on code, ensure you have a [development environment](dev-environment.md) set up, and you are [working on a branch](branches.md)
+To begin working on code, ensure you have a [development environment](../how/dev-environment.md) set up, and you are [working on a branch](../how/branches.md)
 
 {% endblock %}
 
 {% block end_matter %}
 
-Once you have everything working, you can [submit a pull request](submit-pr.md) with your changes.
+Once you have everything working, you can [submit a pull request](../how/submit-pr.md) with your changes.
 
 {% endblock %}
diff --git a/docs/en/content_test_bed/how-to/contribute/how/write-docs.md b/docs/en/content_test_bed/how-to/contribute/how/write-docs.md
@@ -1,15 +1,15 @@
 # Writing documentation
 
-{% extends "contribute/how/write-docs.md" %}
+{% extends "_shared/contribute/how/write-docs.md" %}
 
 {% block front_matter %}
 
-Before you begin writing documentation, ensure you are able to [build the documentation](build-docs.md), and you are [working on a branch](branches.md).
+Before you begin writing documentation, ensure you are able to [build the documentation](../how/build-docs.md), and you are [working on a branch](../how/branches.md).
 
 {% endblock %}
 
 {% block end_matter %}
 
-Once you are happy with your new documentation, you can [submit a pull request](submit-pr.md) with your proposed changes.
+Once you are happy with your new documentation, you can [submit a pull request](../how/submit-pr.md) with your proposed changes.
 
 {% endblock %}
diff --git a/docs/en/content_test_bed/how-to/contribute/index.md b/docs/en/content_test_bed/how-to/contribute/index.md
@@ -1,3 +1,3 @@
 # Contributing to {{ formal_name }}
 
-{% extends "contribute/index.md" %}
+{% extends "_shared/contribute/index.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/next/pr-review.md b/docs/en/content_test_bed/how-to/contribute/next/pr-review.md
@@ -1,3 +1,3 @@
 # Receiving a pull request review
 
-{% extends "contribute/next/pr-review.md" %}
+{% extends "_shared/contribute/next/pr-review.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/next/release.md b/docs/en/content_test_bed/how-to/contribute/next/release.md
@@ -1,3 +1,3 @@
 # The release process
 
-{% extends "contribute/next/release.md" %}
+{% extends "_shared/contribute/next/release.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/policies/ai-policy.md b/docs/en/content_test_bed/how-to/contribute/policies/ai-policy.md
@@ -1,3 +1,3 @@
 <!-- rumdl-disable-file MD041 -->
 
-{% extends "contribute/policies/ai-policy.md" %}
+{% extends "_shared/contribute/policies/ai-policy.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/style/code-style-guide.md b/docs/en/content_test_bed/how-to/contribute/style/code-style-guide.md
@@ -1,3 +1,3 @@
 # Code style guide
 
-{% extends "contribute/style/code-style-guide.md" %}
+{% extends "_shared/contribute/style/code-style-guide.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/style/docs-style-guide.md b/docs/en/content_test_bed/how-to/contribute/style/docs-style-guide.md
@@ -1,3 +1,3 @@
 # Documentation style guide
 
-{% extends "contribute/style/docs-style-guide.md" %}
+{% extends "_shared/contribute/style/docs-style-guide.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/fix-issue.md b/docs/en/content_test_bed/how-to/contribute/what/fix-issue.md
@@ -1,3 +1,3 @@
 # Fixing an issue
 
-{% extends "contribute/what/fix-issue.md" %}
+{% extends "_shared/contribute/what/fix-issue.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/implement-feature.md b/docs/en/content_test_bed/how-to/contribute/what/implement-feature.md
@@ -1,3 +1,3 @@
 # Implementing a new feature
 
-{% extends "contribute/what/implement-feature.md" %}
+{% extends "_shared/contribute/what/implement-feature.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/propose-feature.md b/docs/en/content_test_bed/how-to/contribute/what/propose-feature.md
@@ -1,3 +1,3 @@
 # Proposing a new feature
 
-{% extends "contribute/what/propose-feature.md" %}
+{% extends "_shared/contribute/what/propose-feature.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/review-pr.md b/docs/en/content_test_bed/how-to/contribute/what/review-pr.md
@@ -1,3 +1,3 @@
 # Providing a pull request review
 
-{% extends "contribute/what/review-pr.md" %}
+{% extends "_shared/contribute/what/review-pr.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/translate.md b/docs/en/content_test_bed/how-to/contribute/what/translate.md
@@ -1,3 +1,3 @@
 # Translating content
 
-{% extends "contribute/what/translate.md" %}
+{% extends "_shared/contribute/what/translate.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/triage.md b/docs/en/content_test_bed/how-to/contribute/what/triage.md
@@ -1,3 +1,3 @@
 # Triaging an issue
 
-{% extends "contribute/what/triage.md" %}
+{% extends "_shared/contribute/what/triage.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/use-tools.md b/docs/en/content_test_bed/how-to/contribute/what/use-tools.md
@@ -1,3 +1,3 @@
 # Using the tools
 
-{% extends "contribute/what/use-tools.md" %}
+{% extends "_shared/contribute/what/use-tools.md" %}
diff --git a/docs/en/content_test_bed/how-to/contribute/what/write-docs.md b/docs/en/content_test_bed/how-to/contribute/what/write-docs.md
@@ -1,3 +1,3 @@
 # Adding documentation
 
-{% extends "contribute/what/write-docs.md" %}
+{% extends "_shared/contribute/what/write-docs.md" %}
diff --git a/pyproject.toml b/pyproject.toml
@@ -23,13 +23,13 @@ maintainers = [
 ]
 
 dependencies = [
-    "click==8.3.3",
+    "click==8.4.0",
     "deepl==1.30.0",
     "markdown-checker==1.0.3",
     "mistletoe==1.5.1",
     "mkdocs-autorefs==1.4.4",
     "mkdocs-literate-nav==0.6.3",  # DO NOT UPGRADE - Uncertain whether author's move to ProperDocs will cause incompatibility
-    "mkdocs-macros-plugin==1.5.0",
+    "mkdocs-macros-plugin @ git+https://github.com/kattni/mkdocs-macros-plugin@include-dir-multiple-directories",
     "mkdocs-material==9.7.6",
     "mkdocs-rss-plugin==1.19.0",
     "mkdocs==1.6.1",  # DO NOT UPGRADE - 2+ is not compatible with anything here

diff --git a/src/beeware_docs_tools/live_serve_en.py b/src/beeware_docs_tools/live_serve_en.py
@@ -66,7 +66,6 @@ def serve_docs(
         "mkdocs",
         "serve",
         "--clean",
-        "--livereload",
         "--config-file",
         str(output_path / "mkdocs.en.yml"),
         "--watch",

diff --git a/src/beeware_docs_tools/md_tempdir.py b/src/beeware_docs_tools/md_tempdir.py
@@ -68,14 +68,23 @@ def save_config(project_path, temp_md_path, config, language="en"):
 
     base_path = config["markdown_extensions"]["pymdownx.snippets"].get("base_path", [])
 
+    contribution_root = config["extra"].get(
+        "contribution_guide_root", "how-to/contribute"
+    )
+
     if language != "en":
         shared_content_path = temp_md_path.resolve() / f"shared_content/{language}"
+        local_docs_path = temp_md_path.resolve() / language / contribution_root
     else:
         shared_content_path = (Path(__file__).parent / "shared_content/en").resolve()
+        local_docs_path = (project_path / "docs/en" / contribution_root).resolve()
 
     base_path.append(str(shared_content_path))
     config["markdown_extensions"]["pymdownx.snippets"]["base_path"] = base_path
-    config["plugins"]["macros"]["include_dir"] = str(shared_content_path)
+    config["plugins"]["macros"]["include_dir"] = [
+        str(shared_content_path),
+        str(local_docs_path),
+    ]
 
     with (temp_md_path / "config.yml").open("w", encoding="utf-8") as config_f:
         yaml.dump(config, config_f)

diff --git a/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css b/src/beeware_docs_tools/overrides/assets/stylesheets/beeware_theme.css
@@ -653,3 +653,8 @@ footer.md-footer *, html .md-footer-meta.md-typeset a  {
 .md-typeset table:not([class]) {
     font-size: 1rem;
 }
+
+/* Remove H1 from collapsed content */
+details.abstract h1 {
+    display: none;
+}
diff --git a/.../en/contribute/first-time-contributors.md → ...red/contribute/first-time-contributors.md b/.../en/contribute/first-time-contributors.md → ...red/contribute/first-time-contributors.md
diff --git a/...red_content/en/contribute/how/branches.md → ...ent/en/_shared/contribute/how/branches.md b/...red_content/en/contribute/how/branches.md → ...ent/en/_shared/contribute/how/branches.md
diff --git a/...d_content/en/contribute/how/build-docs.md → ...t/en/_shared/contribute/how/build-docs.md b/...d_content/en/contribute/how/build-docs.md → ...t/en/_shared/contribute/how/build-docs.md
diff --git a/..._content/en/contribute/how/change-note.md → .../en/_shared/contribute/how/change-note.md b/..._content/en/contribute/how/change-note.md → .../en/_shared/contribute/how/change-note.md
diff --git a/...tent/en/contribute/how/dev-environment.md → ..._shared/contribute/how/dev-environment.md b/...tent/en/contribute/how/dev-environment.md → ..._shared/contribute/how/dev-environment.md
@@ -1,14 +1,3 @@
-
-{% if config.extra.website %}
-
-Contributing to BeeWare requires you to pick a project and set up a development environment:
-
-* [Briefcase](https://briefcase.beeware.org/en/stable/how-to/contribute/how/dev-environment/)
-* [Toga](https://toga.beeware.org/en/stable/how-to/contribute/how/dev-environment/)
-* [Rubicon Objective-C](https://rubicon-objc.beeware.org/en/stable/how-to/contribute/how/dev-environment/)
-
-{% else %}
-
 Contributing to {{ formal_name }} requires you to set up a development environment.
 
 ### Prerequisites { #dev-environment-prereqs }
@@ -315,6 +304,4 @@ pre-commit installed at .git/hooks/pre-commit
 
 {% endif %}
 
-{% endif %}
-
 Now you are ready to start hacking on {{ formal_name }}!
diff --git a/...ed_content/en/contribute/how/new-issue.md → ...nt/en/_shared/contribute/how/new-issue.md b/...ed_content/en/contribute/how/new-issue.md → ...nt/en/_shared/contribute/how/new-issue.md
diff --git a/...tent/en/contribute/how/propose-feature.md → ..._shared/contribute/how/propose-feature.md b/...tent/en/contribute/how/propose-feature.md → ..._shared/contribute/how/propose-feature.md
diff --git a/...tent/en/contribute/how/reproduce-issue.md → ..._shared/contribute/how/reproduce-issue.md b/...tent/en/contribute/how/reproduce-issue.md → ..._shared/contribute/how/reproduce-issue.md
diff --git a/...ed_content/en/contribute/how/review-pr.md → ...nt/en/_shared/contribute/how/review-pr.md b/...ed_content/en/contribute/how/review-pr.md → ...nt/en/_shared/contribute/how/review-pr.md
diff --git a/..._content/en/contribute/how/scope-creep.md → .../en/_shared/contribute/how/scope-creep.md b/..._content/en/contribute/how/scope-creep.md → .../en/_shared/contribute/how/scope-creep.md
diff --git a/...ed_content/en/contribute/how/submit-pr.md → ...nt/en/_shared/contribute/how/submit-pr.md b/...ed_content/en/contribute/how/submit-pr.md → ...nt/en/_shared/contribute/how/submit-pr.md
diff --git a/...ed_content/en/contribute/how/translate.md → ...nt/en/_shared/contribute/how/translate.md b/...ed_content/en/contribute/how/translate.md → ...nt/en/_shared/contribute/how/translate.md
diff --git a/...d_content/en/contribute/how/write-code.md → ...t/en/_shared/contribute/how/write-code.md b/...d_content/en/contribute/how/write-code.md → ...t/en/_shared/contribute/how/write-code.md
diff --git a/...d_content/en/contribute/how/write-docs.md → ...t/en/_shared/contribute/how/write-docs.md b/...d_content/en/contribute/how/write-docs.md → ...t/en/_shared/contribute/how/write-docs.md
diff --git a/...ols/shared_content/en/contribute/index.md → ...ed_content/en/_shared/contribute/index.md b/...ols/shared_content/en/contribute/index.md → ...ed_content/en/_shared/contribute/index.md
diff --git a/...d_content/en/contribute/next/pr-review.md → ...t/en/_shared/contribute/next/pr-review.md b/...d_content/en/contribute/next/pr-review.md → ...t/en/_shared/contribute/next/pr-review.md
diff --git a/...red_content/en/contribute/next/release.md → ...ent/en/_shared/contribute/next/release.md b/...red_content/en/contribute/next/release.md → ...ent/en/_shared/contribute/next/release.md
diff --git a/...ntent/en/contribute/policies/ai-policy.md → .../_shared/contribute/policies/ai-policy.md b/...ntent/en/contribute/policies/ai-policy.md → .../_shared/contribute/policies/ai-policy.md
diff --git a/...t/en/contribute/style/code-style-guide.md → ...ared/contribute/style/code-style-guide.md b/...t/en/contribute/style/code-style-guide.md → ...ared/contribute/style/code-style-guide.md
diff --git a/...t/en/contribute/style/docs-style-guide.md → ...ared/contribute/style/docs-style-guide.md b/...t/en/contribute/style/docs-style-guide.md → ...ared/contribute/style/docs-style-guide.md
diff --git a/...d_content/en/contribute/what/fix-issue.md → ...t/en/_shared/contribute/what/fix-issue.md b/...d_content/en/contribute/what/fix-issue.md → ...t/en/_shared/contribute/what/fix-issue.md
@@ -12,54 +12,54 @@ Even if you can't fix the problem, reporting anything you discover during the pr
 
 /// details-abstract | Set up a development environment
 
-{% include "contribute/how/dev-environment.md" %}
+{% include "how/dev-environment.md" %}
 
 ///
 
 /// details-abstract | Work from a branch
 
-{% include "contribute/how/branches.md" %}
+{% include "how/branches.md" %}
 
 ///
 
 /// details-abstract | Reproduce the issue
 
-{% include "contribute/how/reproduce-issue.md" %}
+{% include "how/reproduce-issue.md" %}
 
 ///
 
 **If fixing the issue requires changes to code:**
 
 /// details-abstract | Write, run, and test code
 
-{% include "contribute/how/write-code.md" %}
+{% include "how/write-code.md" %}
 
 ///
 
 **If fixing the issue requires changes to documentation:**
 
 /// details-abstract | Build documentation
 
-{% include "contribute/how/build-docs.md" %}
+{% include "how/build-docs.md" %}
 
 ///
 
 /// details-abstract | Write documentation
 
-{% include "contribute/how/write-docs.md" %}
+{% include "how/write-docs.md" %}
 
 ///
 
 **When you're ready to submit your contribution:**
 
 /// details-abstract | Add a change note
 
-{% include "contribute/how/change-note.md" %}
+{% include "how/change-note.md" %}
 
 ///
 
 /// details-abstract | Submit a pull request
 
-{% include "contribute/how/submit-pr.md" %}
+{% include "how/submit-pr.md" %}
 
 ///