pdm-project · frostming · Mar 23, 2026 · Mar 23, 2026 · Mar 23, 2026 · Mar 23, 2026
diff --git a/.readthedocs.yaml b/.readthedocs.yaml
@@ -10,11 +10,13 @@ build:
   tools:
     python: "3.12"
   jobs:
-    post_create_environment:
+    install:
       - python install-pdm.py --path ~/.local/pdm
       - ~/.local/pdm/bin/pdm --version
-    post_install:
       - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH ~/.local/pdm/bin/pdm install -dG doc
-
-mkdocs:
-  configuration: mkdocs.yml
+    build:
+      html:
+        - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH ~/.local/pdm/bin/pdm run python tasks/render_reference_docs.py
+        - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH ~/.local/pdm/bin/pdm run zensical build
+        - mkdir --parents $READTHEDOCS_OUTPUT/html/
+        - cp --recursive site/. $READTHEDOCS_OUTPUT/html/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -160,12 +160,22 @@ PDM docs development requires a few additional dependencies. Install them as:
 sudo apt install libffi-dev # Or equivalent with the package manager of your choice
 ```
 
+The Zensical-based docs toolchain currently requires Python 3.10+.
+
 Now, whenever you make some changes to the `docs/` and you want to preview the build result, simply do:
 
 ```bash
 pdm run doc
 ```
 
+The CLI and configuration reference pages are generated from
+`tasks/doc_templates/cli.md.in` and `tasks/doc_templates/configuration.md.in`.
+If you change command help text or config metadata, regenerate them with:
+
+```bash
+pdm run python tasks/render_reference_docs.py
+```
+
 ## Release
 
 Once all changes are done and ready to release, you can preview the changelog contents by running:

diff --git a/README.md b/README.md
@@ -7,7 +7,7 @@ A modern Python package and dependency manager supporting the latest PEP standar
 
 ![PDM logo](https://raw.githubusercontent.com/pdm-project/pdm/main/docs/assets/logo_big.png)
 
-[![Docs](https://img.shields.io/badge/Docs-mkdocs-blue?style=for-the-badge)](https://pdm-project.org)
+[![Docs](https://img.shields.io/badge/Docs-zensical-blue?style=for-the-badge)](https://pdm-project.org)
 [![Twitter Follow](https://img.shields.io/twitter/follow/pdm_project?label=get%20updates&logo=twitter&style=for-the-badge)](https://twitter.com/pdm_project)
 [![Discord](https://img.shields.io/discord/824472774965329931?label=discord&logo=discord&style=for-the-badge)](https://discord.gg/Phn8smztpv)
 

diff --git a/docs/assets/extra.css b/docs/assets/extra.css
@@ -1,9 +1,89 @@
+:root {
+  --pdm-brand-primary: #9b6bd3;
+  --pdm-brand-primary-light: #cdb2eb;
+  --pdm-brand-primary-dark: #7343a8;
+  --pdm-brand-accent: #0f8f87;
+  --pdm-brand-accent-soft: rgba(15, 143, 135, 0.14);
+  --pdm-brand-link: #7d46c3;
+  --pdm-brand-focus: rgba(155, 107, 211, 0.28);
+}
+
+[data-md-color-scheme="default"] {
+  --md-primary-fg-color: var(--pdm-brand-primary);
+  --md-primary-fg-color--light: var(--pdm-brand-primary-light);
+  --md-primary-fg-color--dark: var(--pdm-brand-primary-dark);
+  --md-accent-fg-color: var(--pdm-brand-accent);
+  --md-accent-fg-color--transparent: var(--pdm-brand-accent-soft);
+  --md-typeset-a-color: var(--pdm-brand-link);
+  --md-default-bg-color: #fcfaff;
+  --md-default-fg-color: #241a33;
+  --md-default-fg-color--light: #6f5a8d;
+  --md-code-bg-color: #f4eefc;
+  --md-code-fg-color: #472d6b;
+}
+
+[data-md-color-scheme="slate"] {
+  --md-primary-fg-color: #b88fe5;
+  --md-primary-fg-color--light: #d6bdf2;
+  --md-primary-fg-color--dark: #9262c8;
+  --md-accent-fg-color: #54d6ca;
+  --md-accent-fg-color--transparent: rgba(84, 214, 202, 0.16);
+  --md-typeset-a-color: #d0b2f2;
+  --md-default-bg-color: #110d19;
+  --md-default-fg-color: #f0ebf8;
+  --md-default-fg-color--light: #b7aacd;
+  --md-code-bg-color: #1d1629;
+  --md-code-fg-color: #e7dbf9;
+}
+
 a.pdm-expansions {
   cursor: pointer;
   font-weight: bold;
   color: currentColor;
 }
 
+.md-typeset a:hover,
+.md-nav__link:hover,
+.md-tabs__link:hover {
+  color: var(--md-accent-fg-color);
+}
+
+.md-search__form,
+.md-search__input {
+  border-radius: 999px;
+}
+
+.md-search__input,
+.md-typeset .md-button,
+.md-header__button.md-logo {
+  transition: box-shadow 0.2s ease, transform 0.2s ease, background-color 0.2s ease;
+}
+
+.md-search__input:focus,
+.md-search__input:focus-visible,
+.md-typeset .md-button:focus-visible,
+.md-nav__link:focus-visible,
+.md-tabs__link:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 0.2rem var(--pdm-brand-focus);
+}
+
+.md-typeset .md-button--primary {
+  box-shadow: 0 10px 24px rgba(115, 67, 168, 0.18);
+}
+
+.md-typeset .md-button--primary:hover {
+  transform: translateY(-1px);
+}
+
+.md-tabs {
+  box-shadow: inset 0 -1px 0 var(--md-accent-fg-color--transparent);
+}
+
+.md-typeset code {
+  border-radius: 0.35rem;
+}
+
 .bot-container {
   z-index: 9;
   position: fixed;

diff --git a/docs/reference/.gitignore b/docs/reference/.gitignore
@@ -0,0 +1,2 @@
+/cli.md
+/configuration.md
diff --git a/docs/reference/api.md b/docs/reference/api.md
@@ -14,7 +14,8 @@
 
 ## Signals
 
-+++ 1.12.0
+!!! tip
+    Added in 1.12.0.
 
 ::: pdm.signals
     options:

diff --git a/docs/reference/cli.md b/docs/reference/cli.md
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
diff --git a/docs/usage/config.md b/docs/usage/config.md
@@ -336,7 +336,8 @@ url = "https://pkgs.dev.azure.com/[org name]/_packaging/[feed name]/pypi/simple/
 
 ## Exclude specific packages and their dependencies from the lock file
 
-+++ 2.12.0
+!!! tip
+    Added in 2.12.0.
 
 Sometimes you don't even want to include certain packages in the locked file because you are sure they won't be used by any code. In this case, you can completely skip them and their dependencies during dependency resolution:
 
@@ -349,7 +350,8 @@ With this config, `requests` will not be locked in the lockfile, and its depende
 
 ## Passing constant arguments to every pdm invocation
 
-+++ 2.7.0
+!!! tip
+    Added in 2.7.0.
 
 You can add extra options passed to individual pdm commands by `tool.pdm.options` configuration:
 
@@ -365,7 +367,8 @@ These options will be added right after the command name. For instance, based on
 
 ## Ignore package warnings
 
-+++ 2.10.0
+!!! tip
+    Added in 2.10.0.
 
 You may see some warnings when resolving dependencies like this:
 

diff --git a/docs/usage/dependency.md b/docs/usage/dependency.md
@@ -130,7 +130,8 @@ These variables will be read from the environment variables when installing the
 
 ### Add development only dependencies
 
-+++ 1.5.0
+!!! tip
+    Added in 1.5.0.
 
 PDM also supports defining groups of dependencies that are useful for development,
 e.g. some for testing and others for linting. We usually don't want these dependencies to appear in the distribution's metadata
@@ -270,7 +271,8 @@ pdm remove -dG test pytest-cov
 
 ## List outdated packages and the latest versions
 
-+++ 2.13.0
+!!! tip
+    Added in 2.13.0.
 
 To list outdated packages and the latest versions:
 
@@ -330,7 +332,8 @@ In PDM, there are two ways to specify overrides:
 
 ### In the project file
 
-+++ 1.12.0
+!!! tip
+    Added in 1.12.0.
 
 You can specify the overrides in the `pyproject.toml` file, under the `[tool.pdm.resolution.overrides]` table:
 
@@ -345,7 +348,8 @@ Each entry in the table is a package name and a version specifier. The version s
 
 ### Via CLI option
 
-+++ 2.17.0
+!!! tip
+    Added in 2.17.0.
 
 PDM also supports reading dependency overrides from a requirements file. The file works similarly to the constraint file in pip(`--constraint constraints.txt`), and the syntax is the same as the requirements file:
 

diff --git a/docs/usage/lock-targets.md b/docs/usage/lock-targets.md
@@ -1,6 +1,7 @@
 # Lock for specific platforms or Python versions
 
-+++ 2.17.0
+!!! tip
+    Added in 2.17.0.
 
 By default, PDM will try to make a lock file that works on all platforms within the Python versions specified by [`requires-python` in `pyproject.toml`](./project.md#specify-requires-python). This is very convenient during development. You can generate a lock file in your development environment and then use this lock file to replicate the same dependency versions in CI/CD or production environments.