feat!: migrate from Franklin to Zola

.github/workflows/Deploy.yml

@@ -4,19 +4,84 @@ on:
     branches:
       - main
   pull_request:
+
+# One run per branch: superseded PR runs are cancelled, while pushes to main
+# queue behind the run in progress, so close-together commits can never cancel
+# or interleave with a deploy mid-run.
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 jobs:
-  docs:
+  build:
     runs-on: ubuntu-latest
-    permissions: write-all
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@v4
+      - uses: julia-actions/setup-julia@v2
+        with:
+          # The committed MoJuWoPreprocessor Manifest is resolved for 1.12.
+          version: '1.12'
+      - uses: julia-actions/cache@v2
+      - name: Instantiate the preprocessor
+        run: julia --project=MoJuWoPreprocessor -e 'using Pkg; Pkg.instantiate()'
       - name: Set git user config
+        # PkgTemplates reads user.name/user.email from the global git config
+        # when the sharing page generates its demo package.
         run: |
           git config --global user.name "myusername"
           git config --global user.email "myusername@modernjuliaworkflows.github"
-      - name: 🚀 Build and Deploy
-        uses: tlienart/xranklin-build-action@main
+      - name: Execute src/ into content/
+        # Section envs (src/*/Project.toml) are instantiated per page by the
+        # preprocessor itself; their Manifests are not committed.
+        run: julia --project=MoJuWoPreprocessor -m MoJuWoPreprocessor preprocess src content
+      - name: Install Zola
+        uses: taiki-e/install-action@v2
+        with:
+          tool: zola@0.23.3
+      - name: Build the site
+        run: zola build
+      - name: Index the site for search
+        # Builds the Pagefind bundle (public/pagefind/) that js/search.js
+        # loads for the full-text result tier. Runners ship Node for npx.
+        run: npx -y pagefind@1.5.2 --site public
+      - name: Check links
+        # Broken internal links fail the build.
+        # Broken external links only warn (external_level = "warn" in zola.toml's [link_checker]),
+        # since CI cannot reliably reach every site.
+        env:
+          # Zola swallows link-checker warnings at its default log level.
+          RUST_LOG: info
+        run: |
+          set -o pipefail
+          zola check 2>&1 | tee zola-check.log
+          if grep -q "broken external link" zola-check.log; then
+            {
+              echo '### :warning: Broken external links'
+              echo '```'
+              grep -E 'broken external link|^ *[0-9]+\. Broken link' zola-check.log
+              echo '```'
+            } >> "$GITHUB_STEP_SUMMARY"
+            echo "::warning title=Broken external links::zola check found broken external links — see the job summary for the list."
+          fi
+      - name: Upload Pages artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        uses: actions/upload-pages-artifact@v3
         with:
-          DEPLOY: ${{ github.event_name == 'push' }}
-          DEPLOY_BRANCH: 'gh-pages'
-          JULIA_VERSION: '1.11'
+          path: ./public
+
+  deploy:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -1,9 +1,10 @@
-__cache/
-__site/
+content/
+_workdir/
+public/
 .DS_Store
 node_modules/
 package-lock.json
 .vscode
-writing/Manifest.toml
-sharing/Manifest.toml
-optimizing/Manifest.toml
+src/writing/Manifest.toml
+src/sharing/Manifest.toml
+src/optimizing/Manifest.toml

.pre-commit-config.yaml

@@ -0,0 +1,29 @@
+# Vendored third-party code
+exclude: ^static/libs/
+
+repos:
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.48.0
+    hooks:
+      - id: typos
+        priority: 0
+        # Use empty args to avoid overwriting false positives.
+        # Instead, simply fail hook.
+        args: []
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-merge-conflict
+      - id: check-added-large-files
+      - id: check-toml
+      - id: check-yaml
+
+  - repo: https://github.com/fredrikekre/runic-pre-commit
+    rev: v1.0.0
+    hooks:
+    -   id: runic
+
+fail_fast: true

CONTRIBUTING.md

@@ -3,7 +3,33 @@
 If you want to contribute to the blog, start by filing an issue to discuss potential additions.
 Then, you can open a pull request.
 
-We suggest you read the [Franklin documentation](https://franklinjl.org/) first to get familiar with the variant of Markdown syntax used here.
+The pages under `src/` are written in Markdown with executable code blocks, documented below.
+
+## Building the site locally
+
+MoJuWo is built using Julia 1.12 and [Zola](https://www.getzola.org/documentation/getting-started/installation/) `v0.23`.
+
+Install the preprocessor's dependencies once:
+
+```bash
+julia --project=MoJuWoPreprocessor -e 'using Pkg; Pkg.instantiate()'
+```
+
+Then, from the repository root:
+
+```bash
+julia --project=MoJuWoPreprocessor -m MoJuWoPreprocessor serve
+```
+
+The site is built in two steps:
+
+1. a Julia preprocessor ([MoJuWoPreprocessor](MoJuWoPreprocessor/README.md)) executes the code blocks in the authored pages under `src/` and writes the results to the gitignored `content/` directory;
+2. [Zola](https://www.getzola.org) renders `content/` into the static site.
+
+This executes every page (the first pass will take some time),
+serves the site, and watches `src/`:
+saving a page re-runs just that page and live-reloads the browser.
+See [MoJuWoPreprocessor/README.md](MoJuWoPreprocessor/README.md) for the remaining commands (e.g., `preprocess`, `build`, `check`, `clean`).
 
 ## Style guide
 
@@ -20,4 +46,46 @@ Every time a new resource is introduced, it should be accompanied with a link to
 Links to the package documentation are not necessary, unless they are meant to highlight a specific part.
 
 Package names are written as normal text with the .jl extension, while functions or objects are written between backticks.
-Multi-line scripts are given as Julia code or REPL blocks following the Franklin specification.
+Multi-line scripts are given as executable code blocks, so that readers always see real, up-to-date output.
+
+## Executable code blocks
+
+Julia code blocks are executed when the site is built, and their output is rendered below the code like a REPL session.
+The first character of the fence's info string selects the REPL mode, and the rest names the block:
+
+```>example
+x = 1
+x + 1
+```
+
+- ` ```>name ` — julia mode: expressions are echoed and evaluated one by one, like in the REPL;
+- ` ```?name ` — help mode;
+- ` ```]name ` — pkg mode;
+- ` ```;name ` — shell mode;
+- ` ```!name ` — script mode: the code runs silently and is shown as a plain ` ```julia ` block, followed by its printed output. A `# hideall` comment hides the whole block, and a trailing `# hide` hides a single line.
+
+A code block whose error is part of the lesson must be marked with an ` allow-error` flag, e.g. ` ```>name allow-error `: the error message then renders like any other REPL output.
+Without the flag, an erroring code block fails the site build, as does any unclosed fence.
+
+All named fences on a page share one sandbox module, so later blocks can use variables defined in earlier ones.
+Two conventions replace explicit setup code:
+
+- If the page's directory contains a `Project.toml`, that environment is activated while the page runs. Add the packages your code blocks need there.
+- Code blocks run inside a per-page scratch directory, so files are created and read with plain relative paths, exactly as a reader would type them.
+
+## Admonitions
+
+Callout boxes use the components defined in [`templates/components.html`](templates/components.html): `tldr`, `advanced`, and `vscode`.
+The body is regular Markdown:
+
+```markdown
+{% <tldr> %}
+A quick summary of the section.
+{% </tldr> %}
+```
+
+Everything else is standard [Zola](https://www.getzola.org/documentation/):
+the layout lives in `templates/`,
+written as [Tera templates](https://www.getzola.org/documentation/templates/overview/),
+styles live in `static/css/`,
+and the site configuration in `zola.toml`.