Skip to content

Commit 9a93dde

Browse files
br3ndonlandbr3ndonland
committed
Migrate from Material for MkDocs to Zensical
The documentation for this project was previously built with Material for MkDocs, which depends on MkDocs. [MkDocs has suffered from problematic project governance for years](https://fpgmaas.com/blog/collapse-of-mkdocs/). The original author of MkDocs, also the original author of the similarly [problematic HTTPX](https://httpxyz.org/why-fork/), is taking the project in a controversial new direction. [Material for MkDocs has been placed in maintenance mode](https://squidfunk.github.io/mkdocs-material/blog/2025/11/05/zensical/) and there is a newer alternative called [Zensical](https://zensical.org/docs/get-started/). This commit will migrate from Material for MkDocs to Zensical. Zensical offers [compatibility](https://zensical.org/compatibility/) with MkDocs. The same `mkdocs.yml` configuration file can be used if necessary, but the `mkdocs.yml` will be removed in favor of the new `zensical.toml`. Zensical does not have the `--site-dir` option, so it will be set with `site_dir` in `zensical.toml`. The `zensical new` command generates a GitHub Actions workflow for deployment to GitHub Pages. This commit will adapt the Zensical workflow into the existing GitHub Actions workflow, with separate steps for builds and deployments.
1 parent 0d5d48b commit 9a93dde

9 files changed

Lines changed: 239 additions & 59 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 53 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,19 @@ on:
1010
permissions:
1111
contents: read
1212

13+
env:
14+
HATCH_ENV_TYPE_VIRTUAL_PATH: ".venv"
15+
HATCH_VERSION: ">=1.16.3,<1.17"
16+
PIPX_VERSION: ">=1.11,<1.12"
17+
1318
jobs:
1419
ci:
1520
runs-on: ubuntu-latest
1621
strategy:
1722
matrix:
1823
python-version: ["3.10", "3.11", "3.12", "3.13"]
1924
env:
20-
HATCH_ENV_TYPE_VIRTUAL_PATH: ".venv"
2125
HATCH_ENV: "ci"
22-
HATCH_VERSION: ">=1.16.3,<1.17"
23-
PIPX_VERSION: ">=1.11,<1.12"
2426
steps:
2527
- uses: actions/checkout@v6
2628
- uses: actions/setup-python@v6
@@ -72,3 +74,51 @@ jobs:
7274
- name: Publish Python package to PyPI
7375
if: github.ref_type == 'tag' && matrix.python-version == '3.13'
7476
run: hatch publish -n -u __token__ -a ${{ secrets.PYPI_TOKEN }}
77+
78+
docs-build:
79+
name: Build docs
80+
runs-on: ubuntu-latest
81+
env:
82+
HATCH_ENV: "docs"
83+
PYTHON_VERSION: "3.13"
84+
steps:
85+
- uses: actions/checkout@v6
86+
- uses: actions/setup-python@v6
87+
with:
88+
python-version: ${{ env.PYTHON_VERSION }}
89+
- name: Set up pip cache
90+
if: runner.os == 'Linux'
91+
uses: actions/cache@v5
92+
with:
93+
path: ~/.cache/pip
94+
key: ${{ runner.os }}-pip-${{ hashFiles('pyproject.toml') }}
95+
restore-keys: ${{ runner.os }}-pip-
96+
- name: Install pipx for Python ${{ env.PYTHON_VERSION }}
97+
run: python -m pip install "pipx$PIPX_VERSION"
98+
- name: Install Hatch
99+
run: pipx install "hatch$HATCH_VERSION"
100+
- name: Build docs
101+
run: hatch run ${{ env.HATCH_ENV }}:zensical build --clean
102+
- uses: actions/upload-pages-artifact@v4
103+
with:
104+
path: public
105+
106+
docs-deploy:
107+
name: Deploy docs to GitHub Pages
108+
if: github.ref == 'refs/heads/main' || github.ref_type == 'tag'
109+
needs: [ci, docs-build]
110+
concurrency:
111+
cancel-in-progress: true
112+
group: pages
113+
environment:
114+
name: github-pages
115+
url: ${{ steps.deployment.outputs.page_url }}
116+
permissions:
117+
contents: read
118+
id-token: write
119+
pages: write
120+
runs-on: ubuntu-latest
121+
steps:
122+
- name: Deploy site
123+
id: deployment
124+
uses: actions/deploy-pages@v4

‎cspell.json‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,8 @@
2929
"autoformatters",
3030
"autoformatting",
3131
"basedpyright",
32+
"blockquote",
33+
"blockquotes",
3234
"boto",
3335
"br3ndonland",
3436
"brendon",
@@ -99,6 +101,7 @@
99101
"vendorizes",
100102
"venv",
101103
"virtualenv",
102-
"virtualenvs"
104+
"virtualenvs",
105+
"zensical"
103106
]
104107
}

‎docs/assets/images/favicon.png‎

-1.95 KB
Binary file not shown.

‎docs/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ hatch run coverage run
3232

3333
## Documentation
3434

35-
Documentation is built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
35+
Documentation is built with [Zensical](https://zensical.org/).
3636

3737
The [Vercel project configuration](https://vercel.com/docs/project-configuration) in `vercel.json` can be used to deploy the docs to [Vercel](https://vercel.com/docs).
3838

‎docs/markdown.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
icon: simple/markdown
3+
---
4+
5+
# Markdown in 5min
6+
7+
## Headers
8+
9+
```
10+
# H1 Header
11+
## H2 Header
12+
### H3 Header
13+
#### H4 Header
14+
##### H5 Header
15+
###### H6 Header
16+
```
17+
18+
## Text formatting
19+
20+
```
21+
**bold text**
22+
*italic text*
23+
***bold and italic***
24+
~~strikethrough~~
25+
`inline code`
26+
```
27+
28+
## Links and images
29+
30+
```
31+
[Link text](https://example.com)
32+
[Link with title](https://example.com "Hover title")
33+
![Alt text](image.jpg)
34+
![Image with title](image.jpg "Image title")
35+
```
36+
37+
## Lists
38+
39+
```
40+
Unordered:
41+
- Item 1
42+
- Item 2
43+
- Nested item
44+
45+
Ordered:
46+
1. First item
47+
2. Second item
48+
3. Third item
49+
```
50+
51+
## Blockquotes
52+
53+
```
54+
> This is a blockquote
55+
> Multiple lines
56+
>> Nested quote
57+
```
58+
59+
## Code blocks
60+
61+
````
62+
```javascript
63+
function hello() {
64+
console.log("Hello, world!");
65+
}
66+
```
67+
````
68+
69+
## Tables
70+
71+
```
72+
| Header 1 | Header 2 | Header 3 |
73+
|----------|----------|----------|
74+
| Row 1 | Data | Data |
75+
| Row 2 | Data | Data |
76+
```
77+
78+
## Horizontal rule
79+
80+
```
81+
---
82+
or
83+
***
84+
or
85+
___
86+
```
87+
88+
## Task lists
89+
90+
```
91+
- [x] Completed task
92+
- [ ] Incomplete task
93+
- [ ] Another task
94+
```
95+
96+
## Escaping characters
97+
98+
```
99+
Use backslash to escape: \* \_ \# \`
100+
```
101+
102+
## Line breaks
103+
104+
```
105+
End a line with two spaces
106+
to create a line break.
107+
108+
Or use a blank line for a new paragraph.
109+
```

‎mkdocs.yml‎

Lines changed: 0 additions & 52 deletions
This file was deleted.

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ checks = [
2929
"ruff>=0.14,<0.15",
3030
]
3131
docs = [
32-
"mkdocs-material>=9,<10",
32+
"zensical>=0.0.31",
3333
]
3434
tests = [
3535
"coverage[toml]>=7,<8",

‎vercel.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"installCommand": "export HATCH_VERSION=\">=1.16.3,<1.17\" && uv tool install \"hatch$HATCH_VERSION\"",
3-
"buildCommand": "export PATH=\"$HOME/.local/bin:$PATH\" && hatch run docs:mkdocs build --site-dir public",
3+
"buildCommand": "export PATH=\"$HOME/.local/bin:$PATH\" && hatch run docs:zensical build --clean",
44
"cleanUrls": true,
55
"trailingSlash": false
66
}

‎zensical.toml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
# https://zensical.org/docs/setup/basics/
2+
[project]
3+
edit_uri = ""
4+
repo_name = "br3ndonland/template-python"
5+
repo_url = "https://github.com/br3ndonland/template-python"
6+
site_description = "Documentation for the template-python GitHub repo"
7+
site_dir = "public"
8+
site_name = "template-python docs"
9+
site_url = ""
10+
use_directory_urls = false
11+
12+
[project.markdown_extensions.admonition]
13+
14+
[project.markdown_extensions.pymdownx.details]
15+
16+
[project.markdown_extensions.pymdownx.inlinehilite]
17+
18+
[project.markdown_extensions.pymdownx.magiclink]
19+
user = "br3ndonland"
20+
repo = "template-python"
21+
repo_url_shorthand = true
22+
23+
[project.markdown_extensions.pymdownx.snippets]
24+
25+
[project.markdown_extensions.pymdownx.superfences]
26+
27+
[project.markdown_extensions.pymdownx.tasklist]
28+
clickable_checkbox = false
29+
custom_checkbox = true
30+
31+
[project.markdown_extensions.toc]
32+
permalink = true
33+
toc_depth = 3
34+
35+
[project.theme]
36+
features = [
37+
"announce.dismiss", # https://zensical.org/docs/setup/header/#announcement-bar
38+
"content.action.view", # https://zensical.org/docs/setup/repository/#content-actions
39+
"content.code.annotate", # https://zensical.org/docs/authoring/code-blocks/#code-annotations
40+
"content.code.copy", # https://zensical.org/docs/authoring/code-blocks/#code-copy-button
41+
"header.autohide", # https://zensical.org/docs/setup/header/#automatic-hiding
42+
"navigation.instant", # https://zensical.org/docs/setup/navigation/#instant-navigation
43+
"navigation.instant.prefetch", # https://zensical.org/docs/setup/navigation/#instant-prefetching
44+
"navigation.top", # https://zensical.org/docs/setup/navigation/#back-to-top-button
45+
]
46+
font = false
47+
language = "en"
48+
variant = "modern"
49+
50+
# https://zensical.org/docs/setup/logo-and-icons/
51+
[project.theme.icon]
52+
logo = "octicons/book-24"
53+
repo = "octicons/mark-github-16"
54+
55+
# https://zensical.org/docs/setup/colors/
56+
[[project.theme.palette]]
57+
accent = "cyan"
58+
media = "(prefers-color-scheme: dark)"
59+
primary = "cyan"
60+
scheme = "slate"
61+
toggle.icon = "lucide/moon"
62+
toggle.name = "Switch to light mode"
63+
64+
[[project.theme.palette]]
65+
accent = "cyan"
66+
media = "(prefers-color-scheme: light)"
67+
primary = "cyan"
68+
scheme = "default"
69+
toggle.icon = "lucide/sun"
70+
toggle.name = "Switch to dark mode"

0 commit comments

Comments
 (0)