From 20c9d288bd5838e3f0a2b8a8d7cc615c0b93f08a Mon Sep 17 00:00:00 2001
From: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
Date: Sat, 21 Nov 2026 07:50:03 +0000
Subject: [PATCH] ci(lint): lint configuration files and Markdown in CI

---
 RELEASES.md                                               |   12 ++--
 .github/ISSUE_TEMPLATE/bugs.md                            |   10 ++-
 tests/catalog.yaml                                        |    4 +
 CONTRIBUTING.md                                           |    8 +-
 assets/ananke/css/_styles.css                             |    5 +
 .vscode/settings.json                                     |    4 -
 .markdownlintignore                                       |    3 +
 .github/workflows/tests.yml                               |   29 +++++++++
 .yamllint.yml                                             |   13 +++
 .agents/prompts/test-hugo-versions.prompt.md              |    2 
 .github/ISSUE_TEMPLATE/config.yml                         |    4 
 README.md                                                 |    6 +-
 .agents/skills/.markdownlint-cli2.jsonc                   |    7 ++
 package.json                                              |    3 
 scripts/synch-social-icons.md                             |   26 ++++----
 .agents/skills/ananke-hugo-compatibility-testing/SKILL.md |    1 
 .markdownlint-cli2.jsonc                                  |   11 +++
 .agents/references/development.md                         |    3 
 18 files changed, 109 insertions(+), 42 deletions(-)

diff --git a/.agents/prompts/test-hugo-versions.prompt.md b/.agents/prompts/test-hugo-versions.prompt.md
index 45185f6..5b3c0b6 100644
--- a/.agents/prompts/test-hugo-versions.prompt.md
+++ b/.agents/prompts/test-hugo-versions.prompt.md
@@ -2,7 +2,7 @@
 description: Test an Ananke website against multiple local Hugo versions
 ---
 
-# Test ananke websites with local hugo versions
+# Test Ananke websites with local Hugo versions
 
 Use these instructions when testing an Ananke-based website against multiple local Hugo binaries.
 
diff --git a/.agents/references/development.md b/.agents/references/development.md
index 68a78d3..f9849c9 100644
--- a/.agents/references/development.md
+++ b/.agents/references/development.md
@@ -9,7 +9,8 @@
 ## Commands
 
 * `npm run check`: linting, quickstart tests, and the feature coverage gate; browser tests run separately.
-* `npm run lint`: Biome, lockfile-lint, markdownlint, and TypeScript checks.
+* `npm run lint`: Biome, lockfile-lint, markdownlint, TypeScript, and yamllint checks. The `lint` job in `.github/workflows/tests.yml` runs it in CI. yamllint is a Python tool; install it locally, for example with `pipx install yamllint`.
+* `npm run lint:yaml`: yamllint with `.yamllint.yml` on all YAML files that are not ignored.
 * `npm run lint:code:fix`: Biome fixes; HTML templates, Tachyons source, and asset distribution files are excluded by `biome.json`.
 * `npm run lint:markdown:fix`: Markdown fixes.
 * `npm run lint:typescript`: TypeScript checks without emitting files.
diff --git a/.agents/skills/.markdownlint-cli2.jsonc b/.agents/skills/.markdownlint-cli2.jsonc
new file mode 100644
index 0000000..07bc1ff
--- /dev/null
+++ b/.agents/skills/.markdownlint-cli2.jsonc
@@ -0,0 +1,7 @@
+{
+  // Agent skills start with YAML front matter (name, description) and do not
+  // need a top-level heading.
+  "config": {
+    "MD041": false
+  }
+}
diff --git a/.agents/skills/ananke-hugo-compatibility-testing/SKILL.md b/.agents/skills/ananke-hugo-compatibility-testing/SKILL.md
index 8b41d28..b9937b2 100644
--- a/.agents/skills/ananke-hugo-compatibility-testing/SKILL.md
+++ b/.agents/skills/ananke-hugo-compatibility-testing/SKILL.md
@@ -297,4 +297,3 @@
 * Always show when no matching Hugo versions were found.
 * Always distinguish between command output differences and generated site output differences.
 * Always use explicit version numbers in the final summary.
-
diff --git a/.github/ISSUE_TEMPLATE/bugs.md b/.github/ISSUE_TEMPLATE/bugs.md
index c0b5db0..ff9d460 100644
--- a/.github/ISSUE_TEMPLATE/bugs.md
+++ b/.github/ISSUE_TEMPLATE/bugs.md
@@ -20,7 +20,7 @@
 
 -->
 
-## Expected Behavior
+## Expected behavior
 
 <!---
 
@@ -28,7 +28,7 @@
 
 -->
 
-## Current Behavior
+## Current behavior
 
 <!---
 
@@ -36,7 +36,7 @@
 
 -->
 
-## Possible Solution
+## Possible solution
 
 <!---
 
@@ -44,7 +44,7 @@
 
 -->
 
-## Steps to Reproduce
+## Steps to reproduce
 
 <!---
 
@@ -85,6 +85,7 @@
 
 -->
 
+<!-- markdownlint-disable MD033 -->
 <details><summary>Hugo Config</summary>
 <p>
 
@@ -98,3 +99,4 @@
 
 </p>
 </details>
+<!-- markdownlint-enable MD033 -->
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index 146871d..5fc0893 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,8 @@
 blank_issues_enabled: false
 contact_links:
   - name: Build and deployment issues
-    url: https://github.com/gohugo-ananke/ananke/discussions/categories/2-q-a-support
+    url: "https://github.com/gohugo-ananke/ananke/discussions/categories/2-q-a-support"
     about: Please ask and answer questions here. Open a bug report only if you are sure it is a bug.
   - name: Feature requests and problem solutions
-    url: https://github.com/gohugo-ananke/ananke/discussions/categories/3-ideas
+    url: "https://github.com/gohugo-ananke/ananke/discussions/categories/3-ideas"
     about: Please ask and answer questions here. Open a bug report only if you are sure it is a bug.
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index fb80f3d..bac0d85 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -15,6 +15,35 @@
   contents: read
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
+        with:
+          persist-credentials: false
+          submodules: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1
+        with:
+          node-version: "26"
+
+      - name: Install yamllint
+        run: pipx install yamllint==1.38.0
+
+      - name: Show tool versions
+        run: |
+          node --version
+          npm --version
+          yamllint --version
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Code, lockfile, Markdown, TypeScript, and YAML linting
+        run: npm run lint
+
   browser:
     runs-on: ubuntu-latest
     container: mcr.microsoft.com/playwright:v1.65.1-noble
diff --git a/.markdownlint-cli2.jsonc b/.markdownlint-cli2.jsonc
new file mode 100644
index 0000000..6323938
--- /dev/null
+++ b/.markdownlint-cli2.jsonc
@@ -0,0 +1,11 @@
+{
+  // Project additions to @dnbhq/markdownlint-config, which the npm scripts and
+  // lint-staged pass with --config. Settings for one rule replace the shared
+  // settings for that rule, so repeat "ignore" from the shared configuration.
+  "config": {
+    "dnb-title-case-style": {
+      "ignore": ["JavaScript"],
+      "properNouns": ["Ananke", "Hugo", "MIT License"]
+    }
+  }
+}
diff --git a/.markdownlintignore b/.markdownlintignore
index faa67a8..965f4cf 100644
--- a/.markdownlintignore
+++ b/.markdownlintignore
@@ -1,3 +1,6 @@
 CHANGELOG.md
 tests/.playwright/
 tests/fixtures/site/public/
+.github/changelog-old.md
+/PROJECT.md
+/TODO.md
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 24e3faf..4c7e1d9 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -11,9 +11,7 @@
       "addWords": true
     }
   ],
-  "cSpell.dictionaries": [
-    "workspace"
-  ],
+  "cSpell.dictionaries": ["workspace"],
   "cSpell.enabledFileTypes": {
     "markdown": true,
     "plaintext": true,
diff --git a/.yamllint.yml b/.yamllint.yml
index 533f78e..af26154 100644
--- a/.yamllint.yml
+++ b/.yamllint.yml
@@ -5,9 +5,17 @@
 yaml-files:
   - "*.yaml"
   - "*.yml"
-  - "*.md"
 
 ignore: |
+  node_modules/
+  public/
+  resources/
+  scratch/
+  tests/.playwright/
+  tests/fixtures/**/public/
+  .lighthouseci/
+  .playwright-mcp/
+  .wireit/
   .github/workflows/update-netlify.yml
   .github/workflows/daily-audit.yml
   .github/workflows/codeql-analysis.yml
@@ -37,7 +45,8 @@
   indentation:
     spaces: consistent
     indent-sequences: consistent
-    check-multi-line-strings: true
+    # shell scripts in workflow `run` blocks need nested indentation
+    check-multi-line-strings: false
   key-duplicates: enable
   key-ordering: disable
   line-length:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8fb9283..533c7e5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,4 +1,4 @@
-# Contributing to ananke
+# Contributing to Ananke
 
 Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository.
 
@@ -55,7 +55,7 @@
 npm run prepare
 ```
 
- This command is run automatically after `npm install` but you can run it manually to set up hooks in an existing clone or update changed hooks. It uses `simple-git-hooks` to install a commit hook that runs `lint-staged` for markdown files, which in turn runs linting tasks on staged files.
+ This command is run automatically after `npm install` but you can run it manually to set up hooks in an existing clone or update changed hooks. It uses `simple-git-hooks` to install a commit hook that runs `lint-staged`, which lints only the staged files: Biome for JavaScript, TypeScript, and JSON, markdownlint for Markdown, yamllint for YAML, zizmor for workflows, and lockfile-lint for `package-lock.json`. Install [yamllint](https://yamllint.readthedocs.io/) and [zizmor](https://docs.zizmor.sh/) locally, for example with `pipx install yamllint zizmor`.
 
 ## Reporting bugs and requesting features
 
@@ -111,9 +111,11 @@
 4. Run quality checks locally:
 
 ```bash
-npm run lint:markdown
+npm run lint
 ```
 
+ `npm run lint` runs Biome, lockfile-lint, markdownlint, the TypeScript check, and yamllint on the whole repository. The `Theme tests` workflow runs the same command in CI.
+
 1. If your change affects behaviour, validate with Hugo locally (for example `hugo` or `hugo server` in the relevant project).
 2. Open a pull request with:
 
diff --git a/README.md b/README.md
index c3c2586..8d09b82 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,4 @@
-# Ananke Theme for Hugo
+# Ananke theme for Hugo
 
 Ananke is a flexible, production-ready starter theme for [Hugo](https://gohugo.io/) focused on accessibility, performance, and maintainable defaults.
 
@@ -48,7 +48,7 @@
 
 If you are new to Hugo, see Hugo's official quick start: [gohugo.io/getting-started/quick-start](https://gohugo.io/getting-started/quick-start/).
 
-## Getting Started
+## Getting started
 
 After installation, use these guides to configure your site:
 
@@ -57,7 +57,7 @@
 * [Customisation](https://ananke-documentation.netlify.app/customisation/)
 * [Troubleshooting](https://ananke-documentation.netlify.app/troubleshooting/)
 
-## Support and Contributions
+## Support and contributions
 
 * Bug reports: [GitHub Issues](https://github.com/gohugo-ananke/ananke/issues)
 * Questions and feature ideas: [GitHub Discussions](https://github.com/gohugo-ananke/ananke/discussions)
diff --git a/RELEASES.md b/RELEASES.md
index 8875479..494f016 100644
--- a/RELEASES.md
+++ b/RELEASES.md
@@ -1,4 +1,4 @@
-# Release Policy
+# Release policy
 
 This document defines the release workflow for Ananke.
 
@@ -23,7 +23,7 @@
 * `fix: correct mobile navigation`
 * `docs: update configuration guide`
 
-## Branching Model
+## Branching model
 
 ```mermaid
 flowchart LR
@@ -65,7 +65,7 @@
 * Used for testing before release
 * Hosts pre-releases
 
-### feature branches
+### Feature branches
 
 * All work must happen in dedicated branches
 * Branch from `development`
@@ -77,7 +77,7 @@
 * `fix/mobile-menu`
 * `docs/improve-installation`
 
-## Pull Request Workflow
+## Pull request workflow
 
 * All pull requests must target `development`
 * No direct commits to `main` or `development`
@@ -92,7 +92,7 @@
 * clean history in `main`
 * meaningful commit grouping in `development`
 
-## Release Types
+## Release types
 
 ### Pre-releases
 
@@ -116,7 +116,7 @@
 * Tagged as official release
 * Represents stable production state
 
-## Release Flow:
+## Release flow
 
 Typical flow:
 
diff --git a/assets/ananke/css/_styles.css b/assets/ananke/css/_styles.css
index d270a0a..d185d09 100644
--- a/assets/ananke/css/_styles.css
+++ b/assets/ananke/css/_styles.css
@@ -253,7 +253,10 @@
   }
 
   /* Bridge the visual gap so a slow pointer can enter the dropdown. */
-  [data-submenu-mode="hover"] > .ananke-has-submenu > .ananke-submenu-toggle:not([hidden]) + .ananke-submenu::before {
+  [data-submenu-mode="hover"]
+    > .ananke-has-submenu
+    > .ananke-submenu-toggle:not([hidden])
+    + .ananke-submenu::before {
     content: "";
     position: absolute;
     inset-inline: 0;
diff --git a/package.json b/package.json
index 8cd2722..0a96c83 100644
--- a/package.json
+++ b/package.json
@@ -54,6 +54,7 @@
     "lint:markdown": "markdownlint-cli2 --config ./node_modules/@dnbhq/markdownlint-config/.markdownlint-cli2.jsonc \"**/*.{md,mdx}\" \"#CHANGELOG.md\" \"#tests/.playwright/**\" \"#tests/fixtures/site/public/**\" \"#scratch/**\"",
     "lint:markdown:fix": "markdownlint-cli2 --config ./node_modules/@dnbhq/markdownlint-config/.markdownlint-cli2.jsonc --fix \"**/*.{md,mdx}\" \"#CHANGELOG.md\" \"#tests/.playwright/**\" \"#tests/fixtures/site/public/**\" \"#scratch/**\"",
     "lint:typescript": "tsc -p tsconfig.json --noEmit",
+    "lint:yaml": "yamllint --config-file .yamllint.yml .",
     "prepare": "simple-git-hooks install",
     "release": "release-it --config .release-it.ts",
     "release:pre": "release-it --preRelease=prerelease --config .release-it.ts",
@@ -68,7 +69,7 @@
     "release:dry": "release-it --dry-run --config .release-it.ts",
     "lint:code": "biome check",
     "lint:lockfile": "lockfile-lint --path package-lock.json --validate-https --allowed-hosts npm",
-    "lint": "npm run lint:code && npm run lint:lockfile && npm run lint:markdown && npm run lint:typescript",
+    "lint": "npm run lint:code && npm run lint:lockfile && npm run lint:markdown && npm run lint:typescript && npm run lint:yaml",
     "check": "npm run lint && npm test && npm run test:coverage-gate",
     "lint:code:fix": "biome check --write",
     "test:static": "node tests/support/prepare-site.mjs && node tests/support/check-markup.mjs && node tests/support/check-links.mjs",
diff --git a/scripts/synch-social-icons.md b/scripts/synch-social-icons.md
index 62e0ef8..070afea 100644
--- a/scripts/synch-social-icons.md
+++ b/scripts/synch-social-icons.md
@@ -1,20 +1,20 @@
-# synch-social-icons.ts
+# `synch-social-icons.ts`
 
 Synchronises local SVG icons with the upstream `simple-icons` repository.
 
 The script is intended for folders such as `assets/ananke/socials/` that already contain SVG icon files. By default it runs in dry-run mode, compares local files with upstream files from `simple-icons/icons/`, and reports what would change.
 
-- [Usage](#usage)
-- [CLI options](#cli-options)
-- [Behaviour](#behaviour)
-- [Default mode](#default-mode)
-- [Full sync mode](#full-sync-mode)
-- [Output states](#output-states)
-- [Progress output](#progress-output)
-- [JSON output](#json-output)
-- [Recommendations](#recommendations)
-- [Notes](#notes)
-- [Adding new icons](#adding-new-icons)
+* [Usage](#usage)
+* [CLI options](#cli-options)
+* [Behaviour](#behaviour)
+* [Default mode](#default-mode)
+* [Full sync mode](#full-sync-mode)
+* [Output states](#output-states)
+* [Progress output](#progress-output)
+* [JSON output](#json-output)
+* [Recommendations](#recommendations)
+* [Notes](#notes)
+* [Adding new icons](#adding-new-icons)
 
 ## Usage
 
@@ -303,4 +303,4 @@
 * add the new icon to `assets/ananke/socials/` with the correct filename (e.g. `myicon.svg`)
 * it doesn't matter if the content matches the upstream version, as the script will update it
 * run the script in dry-run mode to verify the new icon is detected as `changed`
-* run the script with `--apply` to update the new icon from upstream
\ No newline at end of file
+* run the script with `--apply` to update the new icon from upstream
diff --git a/tests/catalog.yaml b/tests/catalog.yaml
index 6da4a3e..cf4972f 100644
--- a/tests/catalog.yaml
+++ b/tests/catalog.yaml
@@ -15,7 +15,9 @@
   ananke.show_categories:
     tests: ["scripts/test-hugo-quickstart.ts"]
   ananke.copy_code:
-    tests: ["tests/e2e/copy-button.spec.ts", "tests/fixtures/copy-code/copy-code.test.mjs"]
+    tests:
+      - "tests/e2e/copy-button.spec.ts"
+      - "tests/fixtures/copy-code/copy-code.test.mjs"
   ananke.navigation.submenu_mode:
     tests: ["tests/e2e/navigation-modes.spec.ts"]
   ananke.navigation.classes.nav:

--
Gitblit v1.10.0