Migrate documentation to use Zensical instead of MkDocs

For now leave the configuration in mkdocs.yml.

TODO later: Migrate configuration to zensical.toml

Author: tleonhardt

.github/CONTRIBUTING.md

@@ -93,18 +93,17 @@ for a list of dependencies needed for building `cmd2`.
 See the `dev` list under the `[dependency-groups]` heading in [pyproject.toml](../pyproject.toml)
 for a list of dependencies needed for building `cmd2`.
 
-| Prerequisite                                                         | Minimum Version | Purpose                          |
-| -------------------------------------------------------------------- | --------------- | -------------------------------- |
-| [codecov](http://doc.pytest.org/en/latest/)                          | `2.1.13`        | Cover coverage reporting         |
-| [mypy](https://mypy-lang.org/)                                       | `1.13.0`        | Static type checker              |
-| [pytest](https://docs.pytest.org/en/stable/)                         | `3.0.6`         | Unit and integration tests       |
-| [pytest-cov](http://doc.pytest.org/en/latest/)                       | `6.0.0`         | Pytest code coverage             |
-| [pytest-mock](https://pypi.org/project/pytest-mock/)                 | `3.14.0`        | Pytest mocker fixture            |
-| [mkdocs-macros-plugin](https://mkdocs-macros-plugin.readthedocs.io/) | `1.3.7`         | MkDocs Plugin for macros         |
-| [mkdocs-material](https://squidfunk.github.io/mkdocs-material/)      | `9.5.49`        | Documentation                    |
-| [mkdocstrings[python]](https://mkdocstrings.github.io/)              | `0.27.0`        | MkDocs Plugin for Python AutoDoc |
-| [ruff](https://github.com/astral-sh/ruff)                            | `0.7.3`         | Fast linter and formatter        |
-| [uv](https://github.com/astral-sh/uv)                                | `0.5.1`         | Python package management        |
+| Prerequisite                                            | Minimum Version | Purpose                            |
+| ------------------------------------------------------- | --------------- | ---------------------------------- |
+| [codecov](http://doc.pytest.org/en/latest/)             | `2.1.13`        | Cover coverage reporting           |
+| [mypy](https://mypy-lang.org/)                          | `1.13.0`        | Static type checker                |
+| [pytest](https://docs.pytest.org/en/stable/)            | `3.0.6`         | Unit and integration tests         |
+| [pytest-cov](http://doc.pytest.org/en/latest/)          | `6.0.0`         | Pytest code coverage               |
+| [pytest-mock](https://pypi.org/project/pytest-mock/)    | `3.14.0`        | Pytest mocker fixture              |
+| [mkdocstrings[python]](https://mkdocstrings.github.io/) | `0.27.0`        | Zensical plugin for Python AutoDoc |
+| [ruff](https://github.com/astral-sh/ruff)               | `0.7.3`         | Fast linter and formatter          |
+| [uv](https://github.com/astral-sh/uv)                   | `0.5.1`         | Python package management          |
+| [Zensical](https://github.com/zensical/zensical)        | `0.0.17`        | Markdown-based documentation       |
 
 If Python is already installed in your machine, run the following commands to validate the versions:
 
@@ -351,8 +350,8 @@ are primarily related to continuous integration and release deployment.
 
 #### Changes to the documentation files
 
-If you made changes to any file in the `/docs` directory, you need to build the MkDocs documentation
-and make sure your changes look good:
+If you made changes to any file in the `/docs` directory, you need to build the Zensical
+documentation and make sure your changes look good:
 
 ```sh
 $ make docs-test

.github/workflows/docs.yml

@@ -27,5 +27,5 @@ jobs:
           python-version: "3.14"
       - name: Install the project
         run: uv sync --group docs
-      - name: Check if the MkDocs documentation can be built
-        run: uv run mkdocs build -s
+      - name: Check if the Zensical documentation can be built
+        run: uv run zensical build -s

.prettierignore

@@ -1,2 +1,2 @@
-# Markdown documentation files with non-standards syntax for mkdocstrings that Prettier should not auto-format
+# Markdown documentation files with non-standard syntax for mkdocstrings that Prettier should not auto-format
 docs/features/initialization.md

.readthedocs.yaml

@@ -1,5 +1,5 @@
-# Read the Docs configuration file for MkDocs projects
-# See https://docs.readthedocs.io/en/stable/intro/mkdocs.html for details
+# Read the Docs configuration file for Zensical projects
+# See https://docs.readthedocs.com/platform/stable/intro/zensical.html for details
 
 # Required
 version: 2
@@ -10,17 +10,19 @@ version: 2
 #   - epub
 formats: all
 
-# Build documentation in the "docs/" directory with MkDocs
-mkdocs:
-  configuration: mkdocs.yml
-
 # Set the OS, Python version and other tools you might need
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.13"
+    python: latest
   jobs:
     install:
       - pip install .
       - pip install dependency-groups
       - pip-install-dependency-groups docs
+    build:
+      html:
+        - zensical build
+    post_build:
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive site/* $READTHEDOCS_OUTPUT/html/

Makefile

@@ -40,11 +40,11 @@ test: ## Test the code with pytest.
 
 .PHONY: docs-test
 docs-test: ## Test if documentation can be built without warnings or errors
-	@uv run mkdocs build -s
+	@uv run zensical build -s
 
 .PHONY: docs
 docs: ## Build and serve the documentation
-	@uv run mkdocs serve
+	@uv run zensical serve
 
 .PHONY: build
 build: clean-build ## Build wheel file

docs/doc_conventions.md

@@ -62,7 +62,7 @@ See the [Links](https://www.markdownguide.org/basic-syntax/) Markdown syntax doc
 
 ## API Documentation
 
-The API documentation is mostly pulled from docstrings in the source code using the MkDocs
+The API documentation is mostly pulled from docstrings in the source code using the Zensical
 [mkdocstrings](https://mkdocstrings.github.io/) plugin.
 
 When using `mkdocstrings`, it must be preceded by a blank line before and after, i.e.:

docs/features/argument_processing.md

@@ -27,8 +27,8 @@ example to learn more about how to use the various `cmd2` argument processing de
 `cmd2` provides the following [decorators](../api/decorators.md) for assisting with parsing
 arguments passed to commands:
 
-- `cmd2.decorators.with_argparser`
-- `cmd2.decorators.with_argument_list`
+- [cmd2.decorators.with_argparser][]
+- [cmd2.decorators.with_argument_list][]
 
 All of these decorators accept an optional **preserve_quotes** argument which defaults to `False`.
 Setting this argument to `True` is useful for cases where you are passing the arguments to another

docs/javascripts/readthedocs.js

@@ -1,5 +1,5 @@
 document.addEventListener("DOMContentLoaded", function (event) {
-  // Trigger Read the Docs' search addon instead of Material MkDocs default
+  // Trigger Read the Docs' search addon instead of Zensical default
   document.querySelector(".md-search__input").addEventListener("focus", (e) => {
     const event = new CustomEvent("readthedocs-search-show");
     document.dispatchEvent(event);

docs/migrating/minimum.md

@@ -1,9 +1,9 @@
 # Minimum Required Changes
 
-[cmd2.Cmd][] subclasses [cmd.Cmd](https://docs.python.org/3/library/cmd.html#cmd.Cmd) from the
-standard library, and overrides all of the methods other than `Cmd.emptyline` (`cmd2` never calls
-this method). Most apps based on the standard library can be migrated to `cmd2` in just a couple of
-minutes.
+[cmd2.Cmd][] provides all of the same public methods and fields of
+[cmd.Cmd](https://docs.python.org/3/library/cmd.html#cmd.Cmd) from the standard library other than
+`Cmd.emptyline` (`cmd2` never calls this method). Most apps based on the standard library can be
+migrated to `cmd2` in just a couple of minutes.
 
 ## Import and Inheritance
 

pyproject.toml

@@ -40,11 +40,8 @@ dependencies = [
 [dependency-groups]
 build = ["build>=1.2.2", "setuptools>=80.7.1", "setuptools-scm>=9.2"]
 dev = [
-    "black>=25",
     "codecov>=2.1",
     "ipython>=8.23",
-    "mkdocs-git-revision-date-localized-plugin>=1.5",
-    "mkdocs-material>=9.7.1",
     "mkdocstrings[python]>=1",
     "mypy>=1.13",
     "pre-commit>=3",
@@ -53,14 +50,13 @@ dev = [
     "pytest-mock>=3.14.1",
     "ruff>=0.14.10",
     "uv-publish>=1.3",
+    "zensical>=0.0.17",
 ]
 docs = [
-    "black>=25",
-    "mkdocs-git-revision-date-localized-plugin>=1.5",
-    "mkdocs-material>=9.7.1",
     "mkdocstrings[python]>=1",
     "setuptools>=80.7.1",
     "setuptools_scm>=8",
+    "zensical>=0.0.17",
 ]
 quality = ["pre-commit>=3"]
 test = [