migrate to Zensical for documentation (#357)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: joshuadavidthomas

.gitignore

@@ -190,8 +190,9 @@ debug/
 
 # End of https://www.toptal.com/developers/gitignore/api/rust,python
 
-# mkdocs
+# mkdocs / zensical
 site/
+trace.json
 
 # lsp-devtools db
 djls.db

.just/docs.just

@@ -7,21 +7,89 @@ mkdoc_config := justfile_directory() + "/.mkdocs.yml"
 default:
     @just --list --justfile {{ justfile }}
 
+[private]
+[no-cd]
+copy:
+    #!/usr/bin/env sh
+
+    {
+        head -n 1 CHANGELOG.md
+        sed -n '/^## \[Unreleased\]/,$p' CHANGELOG.md \
+            | sed 's](docs/](]g'
+    } > docs/changelog.md
+
+    cat CONTRIBUTING.md \
+        | awk '
+            /^> \[!NOTE\]/ {
+                print "!!! note\n"
+                in_admonition = 1
+                next
+            }
+            in_admonition && /^> / {
+                sub(/^> /, "    ")
+                print
+                next
+            }
+            in_admonition && !/^> / {
+                in_admonition = 0
+            }
+            /^<!-- \[\[\[cog/,/^\]\]\] -->$/ { next }
+            /^<!-- \[\[\[end\]\]\] -->$/ { next }
+            { print }
+        ' \
+        | sed 's](\./]\(https://github.com/joshuadavidthomas/django-language-server/tree/main/]g' \
+        | sed 's](\([^h#:/][^)]*\))]\(https://github.com/joshuadavidthomas/django-language-server/tree/main/\1)]g' \
+        > docs/contributing.md
+
+    {
+        echo "---"
+        echo "title: Home"
+        echo "---"
+        echo ""
+        cat README.md \
+            | awk '
+            BEGIN { in_cog = 0; in_admonition = 0; past_header = 0 }
+            /^# / && !past_header { past_header = 1; print; next }
+            /^<!-- \[\[\[cog/ { in_cog = 1; next }
+            in_cog && /^\]\]\] -->$/ { in_cog = 0; next }
+            in_cog { next }
+            /^<!-- \[\[\[end\]\]\] -->$/ { next }
+            /img\.shields\.io/ { next }
+            /^> \[!CAUTION\]/ {
+                print "!!! warning\n"
+                in_admonition = 1
+                next
+            }
+            in_admonition && /^> / {
+                sub(/^> /, "    ")
+                print
+                next
+            }
+            in_admonition && !/^> / {
+                in_admonition = 0
+            }
+            /^## Documentation$/ { exit }
+            { print }
+            ' \
+            | sed 's](docs/](]g' \
+            | sed 's](LICENSE)]\(https://github.com/joshuadavidthomas/django-language-server/tree/main/LICENSE)]g'
+    } > docs/index.md
+
 [private]
 fmt:
     @just --fmt --justfile {{ justfile }}
 
 # Build documentation
 [no-cd]
-build LOCATION="site":
-    uv run --group docs --frozen mkdocs build --config-file {{ mkdoc_config }} --site-dir {{ LOCATION }}
+build LOCATION="site": copy
+    uv run --group docs --frozen zensical build --clean --config-file {{ mkdoc_config }}
 
 # Serve documentation locally
 [no-cd]
-serve PORT="8000":
+serve PORT="8000": copy
     #!/usr/bin/env sh
     HOST="localhost"
     if [ -f "/.dockerenv" ]; then
         HOST="0.0.0.0"
     fi
-    uv run --group docs --frozen mkdocs serve --config-file {{ mkdoc_config }} --dev-addr localhost:{{ PORT }}
+    uv run --group docs --frozen zensical serve --config-file {{ mkdoc_config }} --dev-addr localhost:{{ PORT }}

.mkdocs.yml

@@ -1,11 +1,11 @@
 # yaml-language-server: $schema=https://squidfunk.github.io/mkdocs-material/schema.json
+copyright: Copyright © 2025 Josh Thomas
 extra_css:
   - stylesheets/extra.css
-hooks:
-  - docs/hooks.py
 markdown_extensions:
   - attr_list
   - admonition
+  - md_in_html
   - pymdownx.emoji:
       emoji_index: !!python/name:material.extensions.emoji.twemoji
       emoji_generator: !!python/name:material.extensions.emoji.to_svg
@@ -24,19 +24,37 @@ markdown_extensions:
       alternate_style: true
       combine_header_slug: true
   - pymdownx.tilde
-plugins:
-  - search
-  - include-markdown:
-      rewrite_relative_urls: false
+  - toc:
+      permalink: true
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Configuration:
+      - configuration/index.md
+      - TagSpecs: configuration/tagspecs.md
+  - Clients:
+      - clients/index.md
+      - Neovim: clients/neovim.md
+      - Sublime Text: clients/sublime-text.md
+      - VS Code: clients/vscode.md
+      - Zed: clients/zed.md
+  - Versioning: versioning.md
+  - Changelog: changelog.md
+  - Contributing: contributing.md
 repo_name: django-language-server
 repo_url: https://github.com/joshuadavidthomas/django-language-server
 site_author: joshuadavidthomas
 site_name: Django Language Server
-site_url: http://joshuadavidthomas.github.io/django-language-server
+site_url: https://djls.joshthomas.dev
 theme:
+  custom_dir: docs/overrides
   features:
+    - navigation.footer
+    - navigation.indexes
     - navigation.instant
+    - navigation.instant.prefetch
     - navigation.instant.progress
+    - navigation.path
     - navigation.sections
     - navigation.tracking
     - search.highlight

.readthedocs.yaml

@@ -11,7 +11,9 @@ build:
   commands:
     - asdf plugin add just && asdf install just latest && asdf global just latest
     - asdf plugin add uv && asdf install uv latest && asdf global uv latest
-    - just docs build $READTHEDOCS_OUTPUT/html
+    - just docs build
+    - mkdir -p $READTHEDOCS_OUTPUT/html
+    - mv site/* $READTHEDOCS_OUTPUT/html
 
 mkdocs:
   configuration: .mkdocs.yml

CONTRIBUTING.md

@@ -10,6 +10,19 @@ We adhere to Django's Code of Conduct in all interactions and expect all contrib
 
 ## Development
 
+The project is written in Rust with IPC for Python communication. Here is a high-level overview of the project and the various crates:
+
+- CLI entrypoint ([`crates/djls/`](./crates/djls/))
+- Configuration management ([`crates/djls-conf/`](./crates/djls-conf/))
+- Django and Python project introspection ([`crates/djls-project/`](./crates/djls-project/))
+- LSP server implementation ([`crates/djls-server/`](./crates/djls-server/))
+- Template parsing ([`crates/djls-templates/`](./crates/djls-templates/))
+- Workspace and document management ([`crates/djls-workspace/`](./crates/djls-workspace/))
+
+Code contributions are welcome from developers of all backgrounds. Rust expertise is valuable for the LSP server and core components, but Python and Django developers should not be deterred by the Rust codebase - Django expertise is just as valuable. Understanding Django's internals and common development patterns helps inform what features would be most valuable.
+
+So far it's all been built by a [a simple country CRUD web developer](https://youtu.be/7ij_1SQqbVo?si=hwwPyBjmaOGnvPPI&t=53) learning Rust along the way - send help!
+
 ### Version Updates
 
 #### Python
@@ -27,59 +40,59 @@ The project uses [`noxfile.py`](noxfile.py) as the single source of truth for su
 
 1. Update [`noxfile.py`](noxfile.py), adding or removing version constants as needed and updating the `PY_VERSIONS` list accordingly.
 
-   For example, given the following versions:
+    For example, given the following versions:
 
-   ```python
-   PY39 = "3.9"
-   PY310 = "3.10"
-   PY311 = "3.11"
-   PY312 = "3.12"
-   PY313 = "3.13"
-   PY_VERSIONS = [PY39, PY310, PY311, PY312, PY313]
-   ```
+    ```python
+    PY39 = "3.9"
+    PY310 = "3.10"
+    PY311 = "3.11"
+    PY312 = "3.12"
+    PY313 = "3.13"
+    PY_VERSIONS = [PY39, PY310, PY311, PY312, PY313]
+    ```
 
-   To add Python 3.14 and remove Python 3.9, the final list will be:
+    To add Python 3.14 and remove Python 3.9, the final list will be:
 
-   ```python
-   PY310 = "3.10"
-   PY311 = "3.11"
-   PY312 = "3.12"
-   PY313 = "3.13"
-   PY314 = "3.14"
-   PY_VERSIONS = [PY310, PY311, PY312, PY313, PY314]
-   ```
+    ```python
+    PY310 = "3.10"
+    PY311 = "3.11"
+    PY312 = "3.12"
+    PY313 = "3.13"
+    PY314 = "3.14"
+    PY_VERSIONS = [PY310, PY311, PY312, PY313, PY314]
+    ```
 
 2. Regenerate auto-generated content:
 
-   ```bash
-   just cog
-   ```
+    ```bash
+    just cog
+    ```
 
-   This updates:
+    This updates:
 
-   - The `requires-python` field in [`pyproject.toml`](pyproject.toml)
-   - Python version trove classifiers in [`pyproject.toml`](pyproject.toml)
-   - Supported versions list in [`README.md`](README.md)
+    - The `requires-python` field in [`pyproject.toml`](pyproject.toml)
+    - Python version trove classifiers in [`pyproject.toml`](pyproject.toml)
+    - Supported versions list in [`README.md`](README.md)
 
 3. Update the lock file:
 
-   ```bash
-   uv lock
-   ```
+    ```bash
+    uv lock
+    ```
 
 4. Test the changes:
 
-   ```bash
-   just testall
-   ```
+    ```bash
+    just testall
+    ```
 
-   Use `just testall` rather than `just test` to ensure all Python versions are tested. The `just test` command only runs against the default versions (the oldest supported Python and Django LTS) and won't catch issues with newly added versions.
+    Use `just testall` rather than `just test` to ensure all Python versions are tested. The `just test` command only runs against the default versions (the oldest supported Python and Django LTS) and won't catch issues with newly added versions.
 
-   If you want, you can also test only a specific Python version across all Django versions by `nox` directly:
+    Alternatively, you can test only a specific Python version across all Django versions by `nox` directly:
 
-   ```bash
-   nox --python 3.14 --session tests
-   ```
+    ```bash
+    nox --python 3.14 --session tests
+    ```
 
 5. Update [`CHANGELOG.md`](CHANGELOG.md), adding entries for any versions added or removed.