🚚 docs: switch generated docs tooling to ProperDocs

Makefile

@@ -132,17 +132,17 @@ docs-trees: ## Regenerate tree blocks in documentation
 	uv run python scripts/gen_tree_docs.py
 
 docs: ensure-docs-coverage-report ## Build documentation
-	uv run mkdocs build --config-file=config/mkdocs.yml
+	uv run properdocs build --config-file=config/mkdocs.yml
 
 docs-serve: ensure-docs-coverage-report ## Serve documentation locally
-	uv run mkdocs serve --config-file=config/mkdocs.yml
+	uv run properdocs serve --config-file=config/mkdocs.yml
 
 docs-serve-open: ensure-docs-coverage-report ## Serve documentation and open in default browser
 	@(sleep 2 && uv run python -m webbrowser "http://127.0.0.1:8000") &
-	uv run mkdocs serve --config-file=config/mkdocs.yml
+	uv run properdocs serve --config-file=config/mkdocs.yml
 
 docs-check: ensure-docs-coverage-report ## Check documentation for issues
-	uv run mkdocs build --config-file=config/mkdocs.yml --strict
+	uv run properdocs build --config-file=config/mkdocs.yml --strict
 
 check-docs: docs-check ## Alias for docs-check
 

docs/concepts/generated-project.md

@@ -8,7 +8,7 @@ Generated projects typically include:
 
 - `src/<package>/` for the main Python package
 - `tests/` for pytest-based tests
-- `config/` for Ruff, MyPy, pytest, MkDocs, and related config
+- `config/` for Ruff, MyPy, pytest, ProperDocs, and related config
 - `docs/` for project documentation
 - `make_cmds/` for Makefile fragments
 - `pyproject.toml` for package metadata and dependencies

docs/development/README.md

@@ -57,7 +57,7 @@ Welcome to the repoman development environment! This guide will help you set up
 - **[Code Quality](code-quality.md)** — Linting (Ruff), type checking (MyPy)
 - **[CLI messages](cli-messages.md)** — Centralized error/warning message text and panels
 - **[Config validation](config-validation.md)** — Pydantic-based answers validation flow
-- **[Documentation](documentation.md)** — MkDocs, Material theme, building docs
+- **[Documentation](documentation.md)** — ProperDocs, Material for MkDocs theme, building docs
 - **[CI](ci.md)** — Continuous integration and local simulation
 - **[Debugging](debugging.md)** — Common issues and debug tools
 - **[Performance Tips](performance-tips.md)** — Fast development workflow

docs/development/additional-resources.md

@@ -10,7 +10,7 @@
 - **[uv Documentation](https://docs.astral.sh/uv/)**: uv package manager guide
 - **[Pytest Documentation](https://docs.pytest.org/)**: Testing framework guide
 - **[Ruff Documentation](https://docs.astral.sh/ruff/)**: Linting and formatting guide
-- **[MkDocs Documentation](https://www.mkdocs.org/)**: Static site generator guide
+- **[ProperDocs Documentation](https://properdocs.org/)**: Static site generator guide
 - **[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)**: Theme documentation
 - **[mkdocstrings Documentation](https://mkdocstrings.github.io/)**: API documentation generator
 

docs/development/documentation.md

@@ -1,6 +1,6 @@
 # Documentation
 
-The project uses **MkDocs** with the **Material theme** for documentation. This provides a modern, responsive documentation site with excellent features like search, navigation, and code highlighting.
+The project uses **ProperDocs** with the **Material for MkDocs theme** for documentation. This provides a modern, responsive documentation site with excellent features like search, navigation, and code highlighting.
 
 ## Documentation Structure
 
@@ -59,7 +59,7 @@ docs
 ```
 <!-- TREE_END -->
 
-MkDocs is configured in `config/mkdocs.yml` (in the repo root). The `docs_dir` points to this `docs/` folder.
+ProperDocs is configured in `config/mkdocs.yml` (in the repo root). The `docs_dir` points to this `docs/` folder.
 
 ## Documentation map
 
@@ -104,7 +104,7 @@ flowchart LR
   update --> troubleshooting
 ```
 
-## MkDocs Configuration
+## ProperDocs Configuration
 
 The documentation is configured in `config/mkdocs.yml` with the following features:
 

docs/development/tools.md

@@ -112,10 +112,10 @@ format:
 	uv run ruff format src/ tests/
 
 docs:
-	uv run mkdocs build --config-file=config/mkdocs.yml
+	uv run properdocs build --config-file=config/mkdocs.yml
 
 docs-serve:
-	uv run mkdocs serve --config-file=config/mkdocs.yml
+	uv run properdocs serve --config-file=config/mkdocs.yml
 
 clean:
 	rm -rf build/ dist/ *.egg-info/ .pytest_cache/ htmlcov/ site/
@@ -130,11 +130,11 @@ To add documentation commands to your Makefile, add these lines:
 #   Documentation     #
 #######################
 docs: ## Build documentation
-	uv run mkdocs build --config-file=config/mkdocs.yml
+	uv run properdocs build --config-file=config/mkdocs.yml
 
 docs-serve: ## Serve documentation locally
-	uv run mkdocs serve --config-file=config/mkdocs.yml
+	uv run properdocs serve --config-file=config/mkdocs.yml
 
 docs-check: ## Check documentation for issues
-	uv run mkdocs build --config-file=config/mkdocs.yml --strict
+	uv run properdocs build --config-file=config/mkdocs.yml --strict
 ```

pyproject.toml

@@ -64,12 +64,11 @@ docs = [
     "mkdocs-literate-nav>=0.6.1",
     "mkdocs-minify-plugin>=0.8.0",
     "mkdocs-jupyter>=0.24.8",
-    "mkdocs>=1.6.1",
     "mkdocstrings[python]>=1.0.0",
     "mkdocs-table-reader-plugin>=3.1.0",
     "mkdocs-charts-plugin>=0.0.13",
     "pymdown-extensions>=10.12",
     "mkdocs-material>=9.7.6",
+    "properdocs>=1.6.7",
 ]
 
-

src/repoman/main_template/README.md.jinja

@@ -13,7 +13,7 @@
 {% if repository_provider == "github" and (not insiders or public_release) -%}
 [![ci](https://github.com/{{ repository_namespace }}/{{ repository_name }}/actions/workflows/ci.yml/badge.svg)](https://github.com/{{ repository_namespace }}/{{ repository_name }}/actions/workflows/ci.yml)
 {% endif -%}
-[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({{ docs_url }}/)
+[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({{ docs_url }}/)
 {% if not insiders or public_release -%}
 [![pypi version](https://img.shields.io/pypi/v/{{ python_package_distribution_name }}.svg)](https://pypi.org/project/{{ python_package_distribution_name }}/)
 {% endif -%}

src/repoman/main_template/config/vscode/launch.json.jinja

@@ -25,7 +25,7 @@
       "name": "docs",
       "type": "debugpy",
       "request": "launch",
-      "module": "mkdocs",
+      "module": "properdocs",
       "justMyCode": false,
       "args": ["serve", "-v"],
       "cwd": "${workspaceFolder}",

src/repoman/main_template/make_cmds/documentation.mk

@@ -5,17 +5,17 @@
 .PHONY: docs
 docs: ## Build documentation
 	@$(call i, Building documentation)
-	uv run mkdocs build --config-file=config/mkdocs.yml
+	uv run properdocs build --config-file=config/mkdocs.yml
 
 .PHONY: docs-serve
 docs-serve: ## Serve documentation locally
 	@$(call i, Serving documentation)
-	uv run mkdocs serve --config-file=config/mkdocs.yml
+	uv run properdocs serve --config-file=config/mkdocs.yml
 
 .PHONY: docs-check
 docs-check: ## Check documentation for issues
 	@$(call i, Checking documentation)
-	uv run mkdocs build --config-file=config/mkdocs.yml --strict
+	uv run properdocs build --config-file=config/mkdocs.yml --strict
 
 .PHONY: check-docs
 check-docs: docs-check ## Alias for docs-check

src/repoman/main_template/pyproject.toml.jinja

@@ -137,8 +137,8 @@ docs = [
     "mkdocs-minify-plugin>=0.8.0",
     "pymdown-extensions>=10.12",
     "mkdocs-jupyter>=0.24.8",
-    "mkdocs>=1.6.1",
     "mkdocstrings[python]>=1.0.0",
     "mkdocs-table-reader-plugin>=3.1.0",
     "mkdocs-charts-plugin>=0.0.13",
+    "properdocs>=1.6.7",
 ]

src/repoman/main_template/{% if repository_provider == 'github' %}.github{% endif %}/workflows/docs.yml.jinja

@@ -60,7 +60,7 @@ jobs:
         python scripts/generate_coverage_badge.py coverage.xml docs/coverage-badge.json
 
     - name: Check docs in strict mode
-      run: uv run mkdocs build --config-file=config/mkdocs.yml --strict
+      run: uv run properdocs build --config-file=config/mkdocs.yml --strict
 
     - name: Upload Pages artifact
       if: {% raw %}${{ github.event_name != 'pull_request' }}{% endraw %}

tests/test_template/test_ci.py

@@ -239,7 +239,9 @@ def test_template_badges_and_urls_render_for_github(tmp_path: Path) -> None:
     repo_url = _expected_repo_url("github", "testuser", "test-project")
 
     assert "[![ci](https://github.com/testuser/test-project/actions/workflows/ci.yml/badge.svg)]" in readme
-    assert f"[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme
+    assert (
+        f"[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme
+    )
     assert "[![pypi version](https://img.shields.io/pypi/v/test-project.svg)]" in readme
     assert "[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)" in readme
     assert "[![python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat)](#installation)" in readme
@@ -280,7 +282,9 @@ def test_template_badges_and_urls_render_for_gitlab(tmp_path: Path) -> None:
     repo_url = _expected_repo_url("gitlab", "testuser", "test-project")
 
     assert "[![ci]" not in readme
-    assert f"[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme
+    assert (
+        f"[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme
+    )
     assert "[![pypi version](https://img.shields.io/pypi/v/test-project.svg)]" in readme
     assert "[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)" in readme
     assert "[![python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat)](#installation)" in readme
@@ -323,7 +327,9 @@ def test_template_badges_and_urls_render_for_azure(tmp_path: Path) -> None:
     repo_url = _expected_repo_url("azure", "testuser", "test-project")
 
     assert "[![ci]" not in readme
-    assert f"[![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme
+    assert (
+        f"[![documentation](https://img.shields.io/badge/docs-properdocs-708FCC.svg?style=flat)]({docs_url}/)" in readme
+    )
     assert "[![pypi version](https://img.shields.io/pypi/v/test-project.svg)]" in readme
     assert "[![license](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](LICENSE)" in readme
     assert "[![python](https://img.shields.io/badge/python-%3E%3D3.11-blue.svg?style=flat)](#installation)" in readme