Add Zensical documentation option

.github/workflows/reusable-cookie.yml

@@ -48,17 +48,17 @@ jobs:
       - name: Test pybind11
         run: nox -s 'tests(pybind11, novcs)' -s 'tests(pybind11, vcs, sphinx)'
 
-      - name: Test scikit-build
-        run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs, sphinx)'
+      - name: Test scikit-build (zensical)
+        run: nox -s 'tests(skbuild, novcs)' -s 'tests(skbuild, vcs, zensical)'
 
       - name: Test poetry
         run: nox -s 'tests(poetry, novcs)' -s 'tests(poetry, vcs, sphinx)'
 
-      - name: Test flit
+      - name: Test flit (mkdocs)
         run: nox -s 'tests(flit, novcs)' -s 'tests(flit, vcs, mkdocs)'
 
-      - name: Test uv
-        run: nox -s 'tests(uv, novcs, sphinx)'
+      - name: Test uv (zensical)
+        run: nox -s 'tests(uv, novcs, zensical)'
 
       - name: Test pdm
         run: nox -s 'tests(pdm, novcs)' -s 'tests(pdm, vcs, sphinx)'
@@ -130,11 +130,11 @@ jobs:
       - name: Test poetry
         run: |
           nox -s 'nox(poetry, novcs, sphinx)'
-          nox -s 'nox(poetry, novcs, mkdocs)' -- docs
+          nox -s 'nox(poetry, novcs, zensical)' -- docs
 
       - name: Test flit
         run: |
-          nox -s 'nox(flit, novcs, mkdocs)'
+          nox -s 'nox(flit, novcs, zensical)'
           nox -s 'nox(flit, novcs, mkdocs)' -- docs
 
       - name: Test pdm
@@ -144,8 +144,8 @@ jobs:
 
       - name: Test maturin
         run: |
-          nox -s 'nox(maturin, novcs, sphinx)'
-          nox -s 'nox(maturin, novcs, sphinx)' -- docs
+          nox -s 'nox(maturin, novcs, zensical)'
+          nox -s 'nox(maturin, novcs, zensical)' -- docs
 
       - name: Test hatch
         run: |

README.md

@@ -17,7 +17,8 @@ templates for Python packages?
   clearly documented and every tool described, and everything is kept in sync.
 - Ten different backends to choose from for building packages.
 - Optional VCS versioning for most backends.
-- Selection for your preferred documentation engine (Sphinx or MkDocs).
+- Selection for your preferred documentation engine (Sphinx, MkDocs, or
+  Zensical).
 - Template generation tested in GitHub Actions using nox.
 - Supports generation with [copier][], [cookiecutter][], and [cruft][].
 - Supports GitHub Actions if targeting a `github.com` url (the default), and
@@ -151,8 +152,7 @@ backports structure with a small typing example.
 - One of several popular licenses
 - A pylint nox target can be used to run pylint, which integrated GHA
   annotations
-- A ReadTheDocs-ready Sphinx or MkDocs `docs/` folder and `docs`
-  dependency-group
+- A ReadTheDocs-ready `docs/` folder and `docs` dependency-group
 - A `tests/` folder and pytest `test` dependency-group
 - A dev group for `uv run` integration
 - A noxfile is included with a few common targets

cookiecutter.json

@@ -18,7 +18,7 @@
     "mesonpy",
     "maturin"
   ],
-  "docs": ["sphinx", "mkdocs"],
+  "docs": ["sphinx", "mkdocs", "zensical"],
   "vcs": true,
   "__year": "{% now 'utc', '%Y' %}",
   "__project_slug": "{{ cookiecutter.project_name | lower | replace('-', '_') | replace('.', '_') }}",
@@ -49,7 +49,8 @@
     "docs": {
       "__prompt__": "Choose your documentation tool",
       "sphinx": "Sphinx",
-      "mkdocs": "MkDocs"
+      "mkdocs": "MkDocs",
+      "zensical": "Zensical (alpha)"
     },
     "vcs": "Use version control for versioning"
   }

copier.yml

@@ -88,6 +88,7 @@ docs:
   choices:
     "Sphinx": sphinx
     "MkDocs": mkdocs
+    "Zensical (alpha)": zensical
   # [[[end]]]
 
 # [[[cog print(cc.vcs.yaml()) ]]]

noxfile.py

@@ -42,6 +42,7 @@
 class Docs(enum.Enum):
     Sphinx = "sphinx"
     MkDocs = "mkdocs"
+    Zensical = "zensical"
 
 
 DIR = Path(__file__).parent.resolve()

{{cookiecutter.project_name}}/.readthedocs.yaml

@@ -17,4 +17,8 @@ build:
       docs $READTHEDOCS_OUTPUT/html
     {%- elif cookiecutter.docs == 'mkdocs' %}
     - uv run mkdocs build --site-dir $READTHEDOCS_OUTPUT/html
+    {%- elif cookiecutter.docs == 'zensical' %}
+    - uv run zensical build
+    - mkdir -p $READTHEDOCS_OUTPUT/html/
+    - cp --recursive site/* $READTHEDOCS_OUTPUT/html/
     {%- endif %}

{{cookiecutter.project_name}}/docs/{% if cookiecutter.docs == 'zensical' %}index.md{% endif %}

@@ -0,0 +1,166 @@
+---
+icon: lucide/rocket
+---
+
+# Get started
+
+For full documentation visit [zensical.org](https://zensical.org/docs/).
+
+## Commands
+
+- [`zensical new`][new] - Create a new project
+- [`zensical serve`][serve] - Start local web server
+- [`zensical build`][build] - Build your site
+
+  [new]: https://zensical.org/docs/usage/new/
+  [serve]: https://zensical.org/docs/usage/preview/
+  [build]: https://zensical.org/docs/usage/build/
+
+## Examples
+
+### Admonitions
+
+> Go to [documentation](https://zensical.org/docs/authoring/admonitions/)
+
+!!! note
+
+    This is a **note** admonition. Use it to provide helpful information.
+
+!!! warning
+
+    This is a **warning** admonition. Be careful!
+
+### Details
+
+> Go to
+> [documentation](https://zensical.org/docs/authoring/admonitions/#collapsible-blocks)
+
+??? info "Click to expand for more info"
+
+    This content is hidden until you click to expand it.
+    Great for FAQs or long explanations.
+
+## Code Blocks
+
+> Go to [documentation](https://zensical.org/docs/authoring/code-blocks/)
+
+```python hl_lines="2" title="Code blocks"
+def greet(name):
+    print(f"Hello, {name}!")  # (1)!
+
+
+greet("Python")
+```
+
+1.  > Go to
+    > [documentation](https://zensical.org/docs/authoring/code-blocks/#code-annotations)
+
+    Code annotations allow to attach notes to lines of code.
+
+Code can also be highlighted inline: `#!python print("Hello, Python!")`.
+
+## Content tabs
+
+> Go to [documentation](https://zensical.org/docs/authoring/content-tabs/)
+
+=== "Python"
+
+    ``` python
+    print("Hello from Python!")
+    ```
+
+=== "Rust"
+
+    ``` rs
+    println!("Hello from Rust!");
+    ```
+
+## Diagrams
+
+> Go to [documentation](https://zensical.org/docs/authoring/diagrams/)
+
+```mermaid
+graph LR
+  A[Start] --> B{Error?};
+  B -->|Yes| C[Hmm...];
+  C --> D[Debug];
+  D --> B;
+  B ---->|No| E[Yay!];
+```
+
+## Footnotes
+
+> Go to [documentation](https://zensical.org/docs/authoring/footnotes/)
+
+Here's a sentence with a footnote.[^1]
+
+Hover it, to see a tooltip.
+
+[^1]: This is the footnote.
+
+## Formatting
+
+> Go to [documentation](https://zensical.org/docs/authoring/formatting/)
+
+- ==This was marked (highlight)==
+- ^^This was inserted (underline)^^
+- ~~This was deleted (strikethrough)~~
+- H~2~O
+- A^T^A
+- ++ctrl+alt+del++
+
+## Icons, Emojis
+
+> Go to [documentation](https://zensical.org/docs/authoring/icons-emojis/)
+
+- :sparkles: `:sparkles:`
+- :rocket: `:rocket:`
+- :tada: `:tada:`
+- :memo: `:memo:`
+- :eyes: `:eyes:`
+
+## Maths
+
+> Go to [documentation](https://zensical.org/docs/authoring/math/)
+
+$$
+\cos x=\sum_{k=0}^{\infty}\frac{(-1)^k}{(2k)!}x^{2k}
+$$
+
+!!! warning "Needs configuration"
+
+    Note that MathJax is included via a `script` tag on this page and is not configured in the generated default configuration to avoid including it in a pages that do not need it. See the documentation for details on how to configure it on all your pages if they are more Maths-heavy than these simple starter pages.
+
+<script id="MathJax-script" async src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script>
+<script>
+  window.MathJax = {
+    tex: {
+      inlineMath: [["\\(", "\\)"]],
+      displayMath: [["\\[", "\\]"]],
+      processEscapes: true,
+      processEnvironments: true
+    },
+    options: {
+      ignoreHtmlClass: ".*|",
+      processHtmlClass: "arithmatex"
+    }
+  };
+</script>
+
+## Task Lists
+
+> Go to
+> [documentation](https://zensical.org/docs/authoring/lists/#using-task-lists)
+
+- [x] Install Zensical
+- [x] Configure `zensical.toml`
+- [x] Write amazing documentation
+- [ ] Deploy anywhere
+
+## Tooltips
+
+> Go to [documentation](https://zensical.org/docs/authoring/tooltips/)
+
+[Hover me][example]
+
+[example]: https://example.com "I'm a tooltip!"

{{cookiecutter.project_name}}/docs/{% if cookiecutter.docs == 'zensical' %}markdown.md{% endif %}

@@ -0,0 +1,109 @@
+---
+icon: simple/markdown
+---
+
+# Markdown in 5min
+
+## Headers
+
+```
+# H1 Header
+## H2 Header
+### H3 Header
+#### H4 Header
+##### H5 Header
+###### H6 Header
+```
+
+## Text formatting
+
+```
+**bold text**
+*italic text*
+***bold and italic***
+~~strikethrough~~
+`inline code`
+```
+
+## Links and images
+
+```
+[Link text](https://example.com)
+[Link with title](https://example.com "Hover title")
+![Alt text](image.jpg)
+![Image with title](image.jpg "Image title")
+```
+
+## Lists
+
+```
+Unordered:
+- Item 1
+- Item 2
+  - Nested item
+
+Ordered:
+1. First item
+2. Second item
+3. Third item
+```
+
+## Blockquotes
+
+```
+> This is a blockquote
+> Multiple lines
+>> Nested quote
+```
+
+## Code blocks
+
+````
+```javascript
+function hello() {
+  console.log("Hello, world!");
+}
+```
+````
+
+## Tables
+
+```
+| Header 1 | Header 2 | Header 3 |
+|----------|----------|----------|
+| Row 1    | Data     | Data     |
+| Row 2    | Data     | Data     |
+```
+
+## Horizontal rule
+
+```
+---
+or
+***
+or
+___
+```
+
+## Task lists
+
+```
+- [x] Completed task
+- [ ] Incomplete task
+- [ ] Another task
+```
+
+## Escaping characters
+
+```
+Use backslash to escape: \* \_ \# \`
+```
+
+## Line breaks
+
+```
+End a line with two spaces
+to create a line break.
+
+Or use a blank line for a new paragraph.
+```