chore(docs): build the docs with pnpm and lint markdown with rumdl

.github/build-docs.sh

@@ -1,3 +1,3 @@
 #!/bin/sh
 
-cd docs && npm install && npm run build
+cd docs && pnpm install --frozen-lockfile && pnpm run build

.github/file-filters.yml

@@ -8,17 +8,22 @@ github_workflows: &github_workflows
 
 doc_files: &doc_files
   - "docs/**"
-  - package.json
-  - package-lock.json
 
 python_all: &python_all
   - "**/*.py"
+  # Linter settings and the resolved linter versions CI installs. Without these,
+  # a dependency bump can change what `ruff check .` reports while python-lint
+  # never runs on the PR that makes the change.
+  - "pyproject.toml"
+  - "uv.lock"
 
 yaml_all: &yaml_all
   - "**/*.{yml,yaml}"
 
 markdown_all: &markdown_all
   - "**/*.{md,mdx}"
+  # [tool.rumdl] lives here, so a rule change has to rerun markdown-lint.
+  - "pyproject.toml"
 
 schema_all: &schema_all
   - "base/**/*.{yml,yaml}"

.github/workflows/changelog-check.yml

@@ -1,5 +1,4 @@
 ---
-# yamllint disable rule:truthy
 name: Changelog
 
 # A release is assembled from news fragments, so every pull request that
@@ -27,7 +26,7 @@ jobs:
     name: News fragment present
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v7
 
       - name: Require a news fragment
         env:

.github/workflows/ci.yml

@@ -1,6 +1,5 @@
 ---
-# yamllint disable rule:truthy rule:truthy rule:line-length
-
+# yamllint disable rule:line-length
 name: "CI"
 on:
   pull_request:
@@ -12,15 +11,22 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+# Least-privilege default; jobs elevate only what they need.
+permissions:
+  contents: read
+
 env:
   GITHUB_PR_NUMBER: ${{ github.event.pull_request.number }}
-  VALE_VERSION: "3.7.1"
+  VALE_VERSION: "3.13.0"
 
 jobs:
   files-changed:
     name: Detect which file has changed
     runs-on: ubuntu-latest
     timeout-minutes: 5
+    permissions:
+      contents: read
+      pull-requests: read  # paths-filter reads changed files via the API on pull_request
     outputs:
       documentation: ${{ steps.changes.outputs.documentation_all }}
       markdown: ${{ steps.changes.outputs.markdown_all }}
@@ -29,7 +35,7 @@ jobs:
       yaml: ${{ steps.changes.outputs.yaml_all }}
     steps:
       - name: "Check out repository code"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v7"
       - name: Check for file changes
         uses: opsmill/paths-filter@v3.0.2
         id: changes
@@ -44,13 +50,13 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: "Check out repository code"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v7"
       - name: "Set up Python"
-        uses: "actions/setup-python@v5"
+        uses: "actions/setup-python@v7"
         with:
           python-version: "3.12"
       - name: "Install uv"
-        uses: "astral-sh/setup-uv@v5"
+        uses: "astral-sh/setup-uv@v7"
         with:
           version: "0.9.18"
       - name: "Install dependencies"
@@ -74,13 +80,13 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: "Check out repository code"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v7"
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - name: "Install uv"
-        uses: "astral-sh/setup-uv@v5"
+        uses: "astral-sh/setup-uv@v7"
         with:
           version: "0.9.18"
       - name: Install dependencies
@@ -96,15 +102,20 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: "Check out repository code"
-        uses: "actions/checkout@v4"
-      - name: "Setup Node.js"
-        uses: "actions/setup-node@v4"
-        with:
-          node-version: "20"
-      - name: "Install markdownlint-cli"
-        run: "npm install -g markdownlint-cli"
-      - name: "Linting: markdownlint"
-        run: "markdownlint '**/*.md' '**/*.mdx'"
+        uses: "actions/checkout@v7"
+      - name: "Set up Python"
+        uses: "actions/setup-python@v7"
+        with:
+          python-version: "3.12"
+      - name: "Install uv"
+        uses: "astral-sh/setup-uv@v7"
+        with:
+          version: "0.9.18"
+      - name: "Install dependencies"
+        run: "uv sync --group dev"
+      # Rules and exclusions live in [tool.rumdl] in pyproject.toml.
+      - name: "Linting: rumdl"
+        run: "uv run rumdl check ."
 
   schema-test:
     name: Test all schema files
@@ -123,15 +134,15 @@ jobs:
       INFRAHUB_VERSION: latest
     steps:
       - name: Check out repository code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           submodules: true
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v7
         with:
           python-version: "3.12"
       - name: "Install uv"
-        uses: "astral-sh/setup-uv@v5"
+        uses: "astral-sh/setup-uv@v7"
         with:
           version: "0.9.18"
       - name: Install dependencies
@@ -176,17 +187,21 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: "Check out repository code"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v7"
         with:
           submodules: true
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 11.6.0
       - name: Install NodeJS
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: 20
-          cache: "npm"
-          cache-dependency-path: docs/package-lock.json
+          node-version: 22  # pnpm 11 requires Node >= 22.13
+          cache: "pnpm"
+          cache-dependency-path: docs/pnpm-lock.yaml
       - name: "Install uv"
-        uses: "astral-sh/setup-uv@v5"
+        uses: "astral-sh/setup-uv@v7"
         with:
           version: "0.9.18"
       - name: "Install Python dependencies"
@@ -200,7 +215,7 @@ jobs:
         working-directory: ./
       - name: "Check for outdated documentation"
         run: |
-          if ! git diff --exit-code -- docs/reference/; then
+          if ! git diff --exit-code -- docs/docs/reference/; then
             echo "::error::Generated documentation is out of date. Please run 'invoke docs.generate' locally and commit the changes."
             exit 1
           fi
@@ -217,17 +232,21 @@ jobs:
     timeout-minutes: 5
     steps:
       - name: "Check out repository code"
-        uses: "actions/checkout@v4"
+        uses: "actions/checkout@v7"
         with:
           submodules: true
+      - name: Install pnpm
+        uses: pnpm/action-setup@v6
+        with:
+          version: 11.6.0
       - name: Install NodeJS
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7
         with:
-          node-version: 20
-          cache: "npm"
-          cache-dependency-path: docs/package-lock.json
+          node-version: 22  # pnpm 11 requires Node >= 22.13
+          cache: "pnpm"
+          cache-dependency-path: docs/pnpm-lock.yaml
       - name: "Install uv"
-        uses: "astral-sh/setup-uv@v5"
+        uses: "astral-sh/setup-uv@v7"
         with:
           version: "0.9.18"
       - name: "Install Python dependencies"

.github/workflows/sync-docs.yml

@@ -1,3 +1,4 @@
+---
 name: Sync Folders
 
 on:
@@ -13,12 +14,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout source repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           path: source-repo
 
       - name: Checkout target repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7
         with:
           repository: opsmill/infrahub-docs
           token: ${{ secrets.PAT_TOKEN }}
@@ -34,4 +35,7 @@ jobs:
           git config user.name github-actions
           git config user.email github-actions@github.com
           git add .
-          if ! (git diff --quiet && git diff --staged --quiet); then git commit -m "Sync docs from schema-library repo" && git push; fi
+          if ! (git diff --quiet && git diff --staged --quiet); then
+            git commit -m "Sync docs from schema-library repo"
+            git push
+          fi

.nvmrc

@@ -1 +1 @@
-20
+22

.yamllint.yml

@@ -5,12 +5,14 @@ ignore:
   - ".venv/"
   - "schema-library/"
   - /.git
-  - /.github
   - "/docs/node_modules/"
+  - "/docs/pnpm-lock.yaml"
 
 rules:
   new-lines: disable
   comments-indentation: disable
+  truthy:
+    check-keys: false  # allow bare `on:` keys in workflows without inline disables
   comments:
     # Changed this to stop a mess between linters from Prettier (vscode) to yamllint
     # See https://github.com/prettier/prettier/pull/10926 or https://github.com/redhat-developer/vscode-yaml/issues/433

changelog/+pnpm-rumdl.housekeeping.md

@@ -0,0 +1,5 @@
+Documentation tooling now matches the other OpsMill repositories. The docs site is built with
+pnpm rather than npm (`docs/pnpm-lock.yaml` replaces `docs/package-lock.json`), and Markdown is
+linted with [rumdl](https://github.com/rvben/rumdl), configured under `[tool.rumdl]` in
+`pyproject.toml`, rather than a globally installed `markdownlint-cli`. CI no longer invokes `npm`
+anywhere. Run `invoke docs.install` and `invoke docs.build` as before; both now shell out to pnpm.

docs/.gitignore

@@ -16,5 +16,6 @@
 .env.production.local
 
 npm-debug.log*
+pnpm-debug.log*
 yarn-debug.log*
 yarn-error.log*

docs/.nvmrc

@@ -1 +1 @@
-20
+22

docs/_templates/home_page.j2

@@ -3,6 +3,7 @@ title: Home
 slug: /
 hide_title: true
 ---
+
 # Schema library for Infrahub
 
 Welcome to the Schema Library for Infrahub! This repository offers a collection of schemas designed to streamline and standardize infrastructure-related data structures.

docs/docs/home.mdx

@@ -3,6 +3,7 @@ title: Home
 slug: /
 hide_title: true
 ---
+
 # Schema library for Infrahub
 
 Welcome to the Schema Library for Infrahub! This repository offers a collection of schemas designed to streamline and standardize infrastructure-related data structures.