Migration to Zensical

.github/workflows/publish.yml

@@ -10,56 +10,45 @@ on:
 concurrency:
   group: publish
   cancel-in-progress: false
-env:
-  GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-  MKDOCS_GIT_COMMITTERS_APIKEY: ${{ secrets.MKDOCS_GIT_COMMITTERS_APIKEY }}
+permissions:
+  contents: read
+  pages: write
+  id-token: write
 jobs:
   deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - name: Checkout latest push
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
-          fetch-depth: 0
+          fetch-depth: 0  # git_info needs full history for page dates
 
-      - name: Setup Python env
-        uses: actions/setup-python@v5
-        with:
-          python-version: 3.9.16
+      - uses: actions/configure-pages@v5
 
-      - name: Set up build cache
-        uses: actions/cache/restore@v4
-        with:
-          key: docs-${{ hashfiles('.cache/**') }}
-          path: .cache
-          restore-keys: |
-            docs-
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
 
-      - name: Setup Github
+      - name: Generate product catalog and homepage news
         run: |
-          git config --local user.email "action@github.com"
-          git config --local user.name "GitHub Action"
-          git pull
-          git checkout master
+          uv run python overrides/hooks/product_catalog.py
+          uv run python overrides/hooks/blog_posts.py
 
-      - name: Install Dependencies
-        run: |
-          make install-python-packages
-          pip install --upgrade "mkdocs-material==9.7.6"
-          sudo apt-get install pngquant
+      - name: Build site
+        run: uv run zensical build --clean
+        env:
+          PYTHONPATH: overrides/hooks  # zensical.toml loads git_info from here
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  # git_info committer lookups
 
-      - name: Deploy Release Version
-        run: |
-          mkdocs gh-deploy --force
+      - name: Generate llms.txt
+        run: uv run python overrides/hooks/llms_txt.py
 
-      - name: Deploy to Server
-        run: |
-          git checkout gh-pages
-          git remote set-url --push origin https://actions:$GITHUB_TOKEN@github.com/ExpressLRS/Docs
-          git push -f origin gh-pages
-
-      - name: Save build cache
-        uses: actions/cache/save@v4
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
         with:
-          key: docs-${{ hashfiles('.cache/**') }}
-          path: .cache
+          path: site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/spellcheck.yml

@@ -14,7 +14,7 @@ jobs:
         uses: actions/checkout@v5
       - name: Install aspell
         run: sudo apt-get install -y aspell aspell-en
-      - name: Install Python packages
-        run: make install-python-packages
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.3.2
       - name: Check Spelling
-        run: make spellcheck
+        run: uv run --group spellcheck pyspelling --config .spellcheck.yml --spellchecker aspell --name Markdown

.gitignore

@@ -147,3 +147,10 @@ Dockerfile.insiders
 
 # Generated product catalog
 docs/assets/data/products.json
+
+# Generated homepage Latest News partial (overrides/hooks/blog_posts.py)
+overrides/partials/recent-posts.html
+
+# Local scratch notes
+TODO.md
+.git-committers.json

.python-version

@@ -0,0 +1 @@
+3.11

Dockerfile

@@ -1,18 +1,10 @@
-FROM squidfunk/mkdocs-material:9.7.6
-RUN apk add \
-    build-base \
-    libxml2-dev \
-    libxslt \
-    libxslt-dev \
-    dumb-init \
-    aspell \
-    aspell-en
+FROM zensical/zensical:0.0.67
 
-WORKDIR /docs
-COPY ./Makefile ./Makefile
-RUN make install-python-packages
+# WORKDIR, EXPOSE 8000, ENTRYPOINT and the default
+# `serve --dev-addr=0.0.0.0:8000` CMD are inherited from the base image.
 
-EXPOSE 8000
+# git_info reads page dates and committers from git
+RUN apk add --no-cache git
 
-ENTRYPOINT ["dumb-init"]
-CMD ["mkdocs", "serve", "--livereload", "--dev-addr=0.0.0.0:8000"]
+# Lets zensical.toml load the git_info Markdown extension
+ENV PYTHONPATH=/docs/overrides/hooks

Makefile

@@ -1,19 +1,36 @@
-.PHONY: install-python-packages
-install-python-packages:
-	pip install \
-      "mkdocs-minify-plugin==0.8.0" \
-      "mkdocs-redirects==1.2.2" \
-      "mkdocs-static-i18n==1.3.0" \
-      "mkdocs-git-committers-plugin-2==2.5.0" \
-      "mkdocs-git-revision-date-localized-plugin==1.4.5" \
-      "cairosvg==2.8.1" \
-      "jinja2==3.1.6" \
-      "pyspelling==2.12.1"
-
-.PHONY: build
+# Host-only convenience wrappers around `uv` and `docker compose`.
+# CI invokes `uv` directly and never calls `make`.
+
+.PHONY: install build run serve site shell spellcheck catalog
+
+# zensical.toml loads git_info from here
+export PYTHONPATH := overrides/hooks
+
+install:
+	uv sync
+
 build:
-	mkdocs build
+	uv run zensical build --clean
+
+run: serve
+
+serve:
+	docker compose up
+
+# Full pipeline, mirrors .github/workflows/publish.yml
+site:
+	docker compose run --rm --entrypoint sh docs -c "\
+	  python3 overrides/hooks/product_catalog.py && \
+	  python3 overrides/hooks/blog_posts.py && \
+	  zensical build --clean && \
+	  python3 overrides/hooks/llms_txt.py"
+
+shell:
+	docker compose run --rm --entrypoint sh docs
+
+catalog:
+	docker compose run --rm --entrypoint python3 docs overrides/hooks/product_catalog.py
 
-.PHONY: spellcheck
+# Needs aspell + aspell-en installed on the host
 spellcheck:
-	pyspelling --config .spellcheck.yml --spellchecker aspell --name Markdown
+	uv run --group spellcheck pyspelling --config .spellcheck.yml --spellchecker aspell --name Markdown

compose.yml

@@ -4,6 +4,8 @@ services:
       context: .
       dockerfile: Dockerfile
     dns_search: ''
+    environment:
+      GITHUB_TOKEN: ${GITHUB_TOKEN:-}  # git_info committer lookups, set in .env
     networks:
       - net
     ports:

docs/assets/javascripts/admonition-enhancement.js

@@ -1,6 +1,8 @@
 // This code helps in linking Table of content with Admonition title
 
-var elements = document.getElementsByClassName('custom-heading');
+// Zensical copies heading markup into the sidebar TOC, so match only the
+// headings in the page body or the TOC entries get removed along with them
+var elements = document.querySelectorAll(':is(h1, h2, h3, h4, h5, h6) > .custom-heading');
 
 for (var i = 0; i < elements.length; i++) {
     var ele = elements[i];
@@ -18,6 +20,6 @@ for (var i = 0; i < elements.length; i++) {
 }
 
 // Removing all custom headings
-while (elements.length) {
-    elements[0].parentElement.remove();
+for (var i = 0; i < elements.length; i++) {
+    elements[i].parentElement.remove();
 }

docs/assets/javascripts/timeago.js

@@ -0,0 +1,14 @@
+// Turns the git_info dates (<span class="timeago" datetime=...>) into "3 months ago"
+document$.subscribe(function() {
+  var rtf = new Intl.RelativeTimeFormat(document.documentElement.lang || "en", { numeric: "auto" })
+  var units = [["year", 31536000], ["month", 2592000], ["week", 604800], ["day", 86400], ["hour", 3600], ["minute", 60]]
+  document.querySelectorAll(".md-source-file .timeago[datetime]").forEach(function(el) {
+    var secs = (Date.parse(el.getAttribute("datetime")) - Date.now()) / 1000
+    for (var i = 0; i < units.length; i++) {
+      if (Math.abs(secs) >= units[i][1] || i === units.length - 1) {
+        el.textContent = rtf.format(Math.round(secs / units[i][1]), units[i][0])
+        break
+      }
+    }
+  })
+})

docs/hardware/spi-receivers.md

@@ -32,7 +32,7 @@ Using the latest [Betaflight Configurator](https://github.com/betaflight/betafli
 If your Flight Controller model is not in the list above, consult your Flight Controller manufacturer for details.
 
 !!! info "NOTE"
-    The Happymodel Mobula6 900MHz AIO with the CrazyF4 ELRS FC (Target: CRAZYBEEF4DX) doesn't use an SPI ExpressLRS receiver. Check the page for [ES915RX](../quick-start/receivers/hmes900.md/#updating-your-receiver-firmware-es915rxes868rx) instead.
+    The Happymodel Mobula6 900MHz AIO with the CrazyF4 ELRS FC (Target: CRAZYBEEF4DX) doesn't use an SPI ExpressLRS receiver. Check the page for [ES915RX](../quick-start/receivers/hmes900.md#updating-your-receiver-firmware-es915rxes868rx) instead.
 
     Likewise, the [v2.0 BetaFPV F4 1S 5A](https://betafpv.com/collections/brushless-flight-controller/products/f4-1s-5a-aio-brushless-flight-controller-elrs-2-4g) comes with an on-board UART-based ExpressLRS Receiver and doesn't use the SPI ExpressLRS implementation. Use the `BETAFPV AIO 2400 RX` Device target.
 

docs/quick-start/receivers/hmpp2400.md

@@ -154,4 +154,3 @@ The next steps will not be able to proceed smoothly and you'll have issues later
 [Configured]: ../receivers/configuring-fc.md
 [firmware options]: ../firmware-options.md
 [Receiver Wiring]: wiring-up.md#connecting-a-receiver
-[Bootloaders]: #bootloaders