mkdocs -> zensical

Author: branchv

Makefile

@@ -5,13 +5,17 @@ all: build test
 .PHONY: build
 build:
 	@rm -rf ./build
-	@PYTHONWARNINGS=ignore uvx copier copy -q --trust --force --vcs-ref=HEAD . ./build
+	@PYTHONWARNINGS=ignore uvx copier copy -q --trust --force --vcs-ref=HEAD -d docs=true -d docker=true . ./build
 
 .PHONY: test
 test:
 	@uv --directory=build run task lint
 	@uv --directory=build run task test -q
 
+.PHONY: docs
+docs:
+	@uv --directory=build run task docs
+
 .PHONY: release
 release:
 	@git tag $(VERSION)

README.md

@@ -22,7 +22,7 @@ uvx copier copy --trust gh:branchv/python-template .
   - Automated versioning, changelog, and release via [Conventional Commits](https://www.conventionalcommits.org/)
   - Automated dependency updates via [Dependabot](https://dependabot.com/)
 - Editor integration: [VS Code](https://code.visualstudio.com/)
-- Documentation: [MkDocs](https://www.mkdocs.org/) (optional)
+- Documentation: [Zensical](https://zensical.org/) (optional)
 - Docker support (optional)
 
 ## Recommended Tools

src/pyproject.toml.jinja

@@ -12,15 +12,12 @@ classifiers = ["Private :: Do Not Upload"]
 {%- endif %}
 
 [dependency-groups]
-{%- if docs %}
-docs = ["mkdocs", "mkdocs-material"]
-{%- endif %}
-dev = ["prek", "pytest", "ruff", "taskipy", "ty"]
+dev = ["prek", "pytest", "ruff", "taskipy", "ty"{%- if docs %}, "zensical"{%- endif %}]
 
 [tool.taskipy.tasks]
 clean = { cmd = "rm -rf .*_cache/ dist/", help = "Remove build artifacts" }
 {% if docs -%}
-docs = { cmd = "mkdocs serve -f docs/mkdocs.yaml", help = "Serve documentation"}
+docs = { cmd = "zensical serve", help = "Serve documentation"}
 {% endif -%}
 lint = { cmd = "prek run --all-files", help = "Run linters and formatters" }
 test = { cmd = "pytest", help = "Run tests" }

src/{% if docs %}docs{% endif %}/index.md

@@ -0,0 +1 @@
+--8<-- "./README.md"

src/{% if docs %}docs{% endif %}/mkdocs.yaml.jinja

@@ -0,0 +1,24 @@
+[project]
+site_name = "{{project_name}}"
+site_description = "{{project_description}}"
+site_url = "https://{{repo_username}}.github.io/{{repo_name}}"
+repo_url = "https://github.com/{{repo_username}}/{{repo_name}}"
+repo_name = "{{repo_username}}/{{repo_name}}"
+nav = [{ "Overview" = "index.md" }]
+
+# https://zensical.org/docs/setup/extensions/
+[project.markdown_extensions]
+admonition = {}
+pymdownx.snippets = { check_paths = true }
+pymdownx.superfences = {}
+toc = { permalink = true }
+
+[[project.theme.palette]]
+scheme = "default"
+toggle.icon = "lucide/sun"
+toggle.name = "Switch to dark mode"
+
+[[project.theme.palette]]
+scheme = "slate"
+toggle.icon = "lucide/moon"
+toggle.name = "Switch to light mode"