CLI reference: the global flags table rendered as a raw template

.github/workflows/cli-drift.yml

@@ -17,7 +17,6 @@ on:
   pull_request:
     paths:
       - 'docs/docs/reference/cli.md'
-      - 'docs/_data/cli-global-flags.yaml'
       - 'scripts/check-cli-drift.py'
       - '.github/workflows/cli-drift.yml'
   workflow_dispatch:

.github/workflows/docs.yml

@@ -58,6 +58,17 @@ jobs:
         working-directory: docs
         run: poetry run zensical build --strict
 
+      # zensical doesn't run Jinja (the macros plugin was silently ignored and
+      # the CLI page shipped a raw `{% for %}` loop), and --strict doesn't
+      # notice. Any template syntax left in a built page fails the build.
+      - name: No unrendered template syntax
+        working-directory: docs
+        run: |
+          if grep -rl --include='*.html' -e '{{ ' -e '{% ' site; then
+            echo "::error::the pages above contain unrendered {{ }} or {% %}"
+            exit 1
+          fi
+
       - name: Upload Pages artifact
         if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
         uses: actions/upload-pages-artifact@v5

docs/docs/reference/cli.md

@@ -65,8 +65,10 @@ and `lib` mode.
 
 | Flag | Effect |
 |---|---|
-{% for row in global_flags %}| {{ row.flag }} | {{ row.effect }} |
-{% endfor %}
+| `-p`, `--path <DIR>` | Run against `<DIR>` instead of the current directory. |
+| `-v`, `--verbose` (repeatable: `-vv`, `-vvv`) | Raise log verbosity (info / debug / trace) for `comline-core` diagnostics. |
+| `-q`, `--quiet` | Only errors. Conflicts with `-v`. |
+| `--plain` | No color, symbols, emoji or spinner — for logs and CI. |
 
 `RUST_LOG` overrides the verbosity flags. `NO_COLOR` strips color. stdout is
 reserved for machine output (`completions` and `targets` write there);

docs/mkdocs.yml

@@ -180,12 +180,8 @@ theme:
 
 
 # TODO: The social plugin is disabled due to not Cairo lib not being available on Nix
-plugins:
+# plugins:
 #  - social
-  - macros:
-      include_yaml:
-        - _data/cli-global-flags.yaml
-      render_by_default: false
 
 extra:
 #  social:

docs/pyproject.toml

@@ -16,7 +16,6 @@ pillow = "^12.3.0"
 mike = "^2.2.0"
 zensical = ">=0.0.57,<0.1.0"
 comline-pygments = { path = "pygments-comline", develop = true }
-mkdocs-macros-plugin = "^1.5.0"
 
 
 

scripts/check-cli-drift.py

@@ -30,9 +30,6 @@
 
 ROOT = Path(__file__).resolve().parent.parent
 DOCS_PAGE = ROOT / "docs/docs/reference/cli.md"
-# The page's tables may be assembled at build time from `_data/*.yaml` by the
-# macros extension, so the documented surface is the page *plus* that data.
-DATA_DIR = ROOT / "docs/_data"
 
 # Inherited by every subcommand; documented once under "Global flags".
 GLOBAL_FLAGS = {"--path", "--verbose", "--quiet", "--plain"}
@@ -130,12 +127,7 @@ def main() -> int:
     if not DOCS_PAGE.exists():
         sys.exit(f"error: {DOCS_PAGE} not found")
 
-    sources = [DOCS_PAGE.read_text(encoding="utf-8")]
-    if DATA_DIR.is_dir():
-        sources += [
-            f.read_text(encoding="utf-8") for f in sorted(DATA_DIR.glob("*.yaml"))
-        ]
-    doc_commands, doc_flags = documented("\n".join(sources))
+    doc_commands, doc_flags = documented(DOCS_PAGE.read_text(encoding="utf-8"))
 
     root_help = run_help([])
     real_commands = parse_commands(root_help)