mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
13 hours ago 20c9d288bd5838e3f0a2b8a8d7cc615c0b93f08a
ci(lint): lint configuration files and Markdown in CI

Add a lint job to the Theme tests workflow that runs `npm run lint`.
The lint script now also runs yamllint (`lint:yaml`) on all YAML files.

Make the repository pass the full lint run:

* add a project markdownlint config with proper nouns (Ananke, Hugo,
MIT License) and allow skills without a top-level heading
* ignore the old changelog and local PROJECT.md and TODO.md
* scope yamllint to YAML files, ignore generated folders, and allow
nested indentation in workflow shell scripts
* fix heading case, list style, Biome formatting, and quoted URLs

The pre-commit hook already lints only staged Markdown files through
lint-staged.

Closes #1021

Signed-off-by: Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
16 files modified
2 files added
151 ■■■■■ changed files
.agents/prompts/test-hugo-versions.prompt.md 2 ●●●●● patch | view | raw | blame | history
.agents/references/development.md 3 ●●●●● patch | view | raw | blame | history
.agents/skills/.markdownlint-cli2.jsonc 7 ●●●●● patch | view | raw | blame | history
.agents/skills/ananke-hugo-compatibility-testing/SKILL.md 1 ●●●●● patch | view | raw | blame | history
.github/ISSUE_TEMPLATE/bugs.md 10 ●●●●● patch | view | raw | blame | history
.github/ISSUE_TEMPLATE/config.yml 4 ●●●●● patch | view | raw | blame | history
.github/workflows/tests.yml 29 ●●●●● patch | view | raw | blame | history
.markdownlint-cli2.jsonc 11 ●●●●● patch | view | raw | blame | history
.markdownlintignore 3 ●●●●● patch | view | raw | blame | history
.vscode/settings.json 4 ●●●●● patch | view | raw | blame | history
.yamllint.yml 13 ●●●●● patch | view | raw | blame | history
CONTRIBUTING.md 8 ●●●●● patch | view | raw | blame | history
README.md 6 ●●●●● patch | view | raw | blame | history
RELEASES.md 12 ●●●●● patch | view | raw | blame | history
assets/ananke/css/_styles.css 5 ●●●●● patch | view | raw | blame | history
package.json 3 ●●●●● patch | view | raw | blame | history
scripts/synch-social-icons.md 26 ●●●●● patch | view | raw | blame | history
tests/catalog.yaml 4 ●●●●● patch | view | raw | blame | history
.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.
.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.
.agents/skills/.markdownlint-cli2.jsonc
New file
@@ -0,0 +1,7 @@
{
  // Agent skills start with YAML front matter (name, description) and do not
  // need a top-level heading.
  "config": {
    "MD041": false
  }
}
.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.
.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 -->
.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.
.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
.markdownlint-cli2.jsonc
New file
@@ -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"]
    }
  }
}
.markdownlintignore
@@ -1,3 +1,6 @@
CHANGELOG.md
tests/.playwright/
tests/fixtures/site/public/
.github/changelog-old.md
/PROJECT.md
/TODO.md
.vscode/settings.json
@@ -11,9 +11,7 @@
      "addWords": true
    }
  ],
  "cSpell.dictionaries": [
    "workspace"
  ],
  "cSpell.dictionaries": ["workspace"],
  "cSpell.enabledFileTypes": {
    "markdown": true,
    "plaintext": true,
.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:
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:
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)
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:
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;
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",
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
* run the script with `--apply` to update the new icon from upstream
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: