Upgrade to Zensical (MK Docs follow up) and other fixes

.github/workflows/check_pr.yml

@@ -5,32 +5,46 @@ on:
   workflow_dispatch:
 
 jobs:
-  check-pull-request:
+  link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@master
-      with:
-        fetch-depth: 0
-
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
-      with:
-        check-modified-files-only: 'yes'
-        base-branch: main
-
-    - uses: tj-actions/changed-files@v40
-      id: changed-files
-      with:
-        files: '**/*.md'
-        separator: ","
-
-    - uses: DavidAnson/markdownlint-cli2-action@v14
-      continue-on-error: false
-      if: steps.changed-files.outputs.any_changed == 'true'
-      with:
-        globs: ${{ steps.changed-files.outputs.all_changed_files }}
-        separator: ","
-        config: '.markdownlint.json'
-
-    - run: pip install -r requirements.txt
-    - run: mkdocs build -s -v
+      - uses: actions/checkout@master
+        with:
+          fetch-depth: 0
 
+      - uses: tcort/github-action-markdown-link-check@v1
+        with:
+          check-modified-files-only: "yes"
+          base-branch: main
+          config-file: ".github/workflows/mlc_config.json"
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+        with:
+          fetch-depth: 0
+
+      - uses: tj-actions/changed-files@v40
+        id: changed-files
+        with:
+          files: "**/*.md"
+          separator: ","
+
+      - uses: DavidAnson/markdownlint-cli2-action@v20
+        continue-on-error: false
+        if: steps.changed-files.outputs.any_changed == 'true'
+        with:
+          globs: ${{ steps.changed-files.outputs.all_changed_files }}
+          separator: ","
+          config: ".markdownlint.jsonc"
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@master
+        with:
+          fetch-depth: 0
+
+      - run: pip install -r requirements.txt
+      - run: zensical build --clean

.github/workflows/mlc_config.json

@@ -0,0 +1,11 @@
+{
+  "ignorePatterns": [
+    {
+      "pattern": "/TODO$"
+    },
+    {
+      "pattern": "^mailto:"
+    }
+  ],
+  "aliveStatusCodes": [200, 202, 206, 403]
+}

.github/workflows/publish.yml

@@ -0,0 +1,37 @@
+name: Publish site
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment, don't cancel in-progress runs
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/configure-pages@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - run: zensical build --clean
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+      - uses: actions/deploy-pages@v4
+        id: deployment

.markdownlint.jsonc

@@ -0,0 +1,100 @@
+{
+    // markdownlint config tuned for compatibility with the Zensical toolchain
+    // (https://zensical.org/studio/write/linting/).
+    //
+    // Zensical Studio ships its own Markdown auto-formatter + linter. To avoid
+    // fighting it we split responsibilities:
+    //
+    //   * Zensical auto-formatter  -> owns style (list markers, blank lines,
+    //     fences, tables, emphasis, headings, trailing whitespace, line
+    //     endings). Every markdownlint rule the formatter rewrites is disabled
+    //     below so formatter output always passes `markdownlint`.
+    //   * Zensical linter (default rules) -> owns heading/level-skip (MD001),
+    //     link/empty-destination (MD042), image/missing-alt (MD045). Disabled
+    //     here to avoid duplicate reports.
+    //   * markdownlint -> keeps the content/structure checks that neither
+    //     Zensical tool enforces by default, plus the rules that map to
+    //     Zensical *opt-in* rules (MD025, MD033, MD040, MD041) so they stay
+    //     enforced in CI even for contributors who don't use Studio.
+
+    "default": true,
+
+    // --- Owned by the Zensical auto-formatter (style) ---
+    "MD003": false, // heading style
+    "MD004": false, // unordered list marker style
+    "MD009": false, // trailing spaces
+    "MD010": false, // hard tabs
+    "MD012": false, // multiple consecutive blank lines
+    "MD018": false, // space after ATX hash
+    "MD019": false, // multiple spaces after ATX hash
+    "MD020": false, // space inside closed ATX hash
+    "MD021": false, // multiple spaces inside closed ATX hash
+    "MD022": false, // blank lines around headings
+    "MD023": false, // headings must start at line start
+    "MD027": false, // multiple spaces after blockquote symbol
+    "MD029": false, // ordered list item prefix
+    "MD030": false, // spaces after list markers
+    "MD031": false, // blank lines around fenced code blocks
+    "MD032": false, // blank lines around lists
+    "MD035": false, // horizontal rule style
+    "MD037": false, // spaces inside emphasis markers
+    "MD038": false, // spaces inside code span elements
+    "MD039": false, // spaces inside link text
+    "MD047": false, // single trailing newline
+    "MD048": false, // code fence style
+    "MD049": false, // emphasis style
+    "MD050": false, // strong style
+    "MD054": false, // link/image style
+    "MD055": false, // table pipe style
+    "MD058": false, // blank lines around tables
+    "MD060": false, // table column style
+
+    // --- Covered by the Zensical linter's default rules ---
+    "MD001": false, // -> heading/level-skip
+    "MD042": false, // -> link/empty-destination
+    "MD045": false, // -> image/missing-alt
+
+    // MD046 (code block style) is off: markdownlint has no admonition support,
+    // so the 4-space-indented body of `!!! note` / `???+ info` blocks is
+    // misread as an indented code block, making the "consistent" check
+    // meaningless. Zensical's code/indented rule is opt-in and left off.
+    "MD046": false,
+
+    // --- Kept: content/structure checks, with project overrides ---
+    "MD007": {
+        // 4-space nested list indent is a hard requirement of Python Markdown,
+        // which Zensical renders with; its linter does not guard this.
+        "indent": 4
+    },
+    // MD013 (line length) is off: the Zensical auto-formatter does not wrap
+    // prose, so a hard column limit would fight it. Re-enable with
+    // { "tables": false, "code_blocks": false } if you want it back.
+    "MD013": false,
+    "MD024": {
+        "siblings_only": true
+    },
+    "MD025": {
+        "front_matter_title": ""
+    },
+    "MD026": {
+        "punctuation": ".,;:。："
+    },
+    "MD033": {
+        // Zensical's html/disallowed rule is opt-in (off), so it permits all
+        // of these. This list mirrors the inline HTML the docs actually use.
+        "allowed_elements": [
+            "div",
+            "p",
+            "a",
+            "br",
+            "sup",
+            "sub",
+            "kbd",
+            "small",
+            "abbr",
+            "span",
+            "details",
+            "summary"
+        ]
+    }
+}

.pre-commit-config.yaml

@@ -1,11 +1,18 @@
+# markdownlint is scoped to the rules the Zensical toolchain leaves to it;
+# see .markdownlint.jsonc for the rationale.
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v2.3.0
+    rev: v6.0.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
+        # Matches .editorconfig insert_final_newline = true (applies to *.md too).
       - id: trailing-whitespace
+        # Markdown trailing whitespace is significant (hard line breaks) and
+        # .editorconfig exempts *.md; leave *.md to the Zensical formatter.
+        exclude_types: [markdown]
   - repo: https://github.com/DavidAnson/markdownlint-cli2
-    rev: v0.14.0
+    rev: v0.23.2
     hooks:
       - id: markdownlint-cli2
+        # Auto-discovers .markdownlint.jsonc at the repo root.

README.md

@@ -7,9 +7,10 @@ Soar cognitive architecture, including source for the PDF's distributed with Soa
 
 The website is not yet fully migrated from the old site, and is still under construction.
 
-The site is built using the [MkDocs](https://www.mkdocs.org/), a static site
-generator that uses Markdown files to generate a website. The theme is
-[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/).
+The site is built with [Zensical](https://zensical.org/), a static site
+generator from the Material for MkDocs team that uses Markdown files to
+generate a website. It reads the existing `mkdocs.yml` config and renders
+with the Material "classic" theme variant.
 
 Large files that are not displayed but rather downloaded should not be stored here;
 instead, put them in the [website downloads repository](https://github.com/SoarGroup/website-downloads)
@@ -19,9 +20,9 @@ and link to them here.
 
 ```shell
 python -m venv venv
-source venv/bin/activate (or venv\Scripts\activate on Windows)
+source venv/bin/activate # (or venv\Scripts\activate on Windows)
 pip install -r requirements.txt
-mkdocs serve # add -s to abort on any warnings
+zensical serve # add -s to abort on any warnings; zensical build for a one-off build
 ```
 
 ## Deployment
@@ -30,6 +31,10 @@ The site is deployed to GitHub Pages automatically as long as the build workflow
 don't fail. Run it locally to ensure you haven't introduced an error, and then
 just push your commit to the `main` branch and the site will be updated automatically.
 
+Deployment uses the GitHub Actions Pages pipeline (`.github/workflows/publish.yml`,
+`zensical build` + `actions/deploy-pages`). The repository's *Settings → Pages →
+Build and deployment → Source* must be set to **GitHub Actions**.
+
 ## Updates for New Soar Versions
 
 *   Update the `soar_version` variable in `mkdocs.yml`.

docs/development/SoarTechnicalFAQ.md

@@ -283,7 +283,7 @@ is a good model to follow. If you're working on a command line application
 without a GUI, then the _TestCommandLine_ application is a good reference as it
 demonstrates how to support interruption in a single-threaded application.
 
-A detailed explanation about threads in Soar is provided [here](../development/soar/ThreadsInSML.md).
+A detailed explanation about threads in Soar is provided in [Threads in SML](../development/soar/ThreadsInSML.md).
 
 ## How do I properly manage memory in my SML application?
 

docs/downloads/agent_development_tools/soar_data_collector.md

@@ -25,8 +25,8 @@ Statistics are collected at configurable intervals during a run and include:
 
 No pre-built binaries are currently available for this project.
 
-*   The project repository is [here](https://github.com/voigtjr/soar-datacollector)
-*   A JSoar version is also available [here](https://github.com/voigtjr/jsoar-datacollector)
+*   The [project repository](https://github.com/voigtjr/soar-datacollector) is on GitHub
+*   A [JSoar version](https://github.com/voigtjr/jsoar-datacollector) is also available
 
 ## Documentation
 

docs/downloads/agent_development_tools/soareditor.md

@@ -31,7 +31,7 @@ the plugin.
 
 ## Documentation
 
-While there isn't much documentation yet, you can find a page on the basics [here](https://github.com/SoarGroup/Soar-Editor/wiki/Using-the-Soar-Editor).
+While there isn't much documentation yet, you can find a [page on the basics](https://github.com/SoarGroup/Soar-Editor/wiki/Using-the-Soar-Editor).
 
 ## Developers