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
| | |
| | | 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. |
| | | |
| | |
| | | ## 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. |
| New file |
| | |
| | | { |
| | | // Agent skills start with YAML front matter (name, description) and do not |
| | | // need a top-level heading. |
| | | "config": { |
| | | "MD041": false |
| | | } |
| | | } |
| | |
| | | * 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. |
| | | |
| | |
| | | |
| | | --> |
| | | |
| | | ## Expected Behavior |
| | | ## Expected behavior |
| | | |
| | | <!--- |
| | | |
| | |
| | | |
| | | --> |
| | | |
| | | ## Current Behavior |
| | | ## Current behavior |
| | | |
| | | <!--- |
| | | |
| | |
| | | |
| | | --> |
| | | |
| | | ## Possible Solution |
| | | ## Possible solution |
| | | |
| | | <!--- |
| | | |
| | |
| | | |
| | | --> |
| | | |
| | | ## Steps to Reproduce |
| | | ## Steps to reproduce |
| | | |
| | | <!--- |
| | | |
| | |
| | | |
| | | --> |
| | | |
| | | <!-- markdownlint-disable MD033 --> |
| | | <details><summary>Hugo Config</summary> |
| | | <p> |
| | | |
| | |
| | | |
| | | </p> |
| | | </details> |
| | | <!-- markdownlint-enable MD033 --> |
| | |
| | | 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. |
| | |
| | | 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 |
| New file |
| | |
| | | { |
| | | // 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"] |
| | | } |
| | | } |
| | | } |
| | |
| | | CHANGELOG.md |
| | | tests/.playwright/ |
| | | tests/fixtures/site/public/ |
| | | .github/changelog-old.md |
| | | /PROJECT.md |
| | | /TODO.md |
| | |
| | | "addWords": true |
| | | } |
| | | ], |
| | | "cSpell.dictionaries": [ |
| | | "workspace" |
| | | ], |
| | | "cSpell.dictionaries": ["workspace"], |
| | | "cSpell.enabledFileTypes": { |
| | | "markdown": true, |
| | | "plaintext": true, |
| | |
| | | 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 |
| | |
| | | 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 to ananke |
| | | # Contributing to Ananke |
| | | |
| | | Thanks for helping improve Ananke. This document describes the current contribution workflow for this repository. |
| | | |
| | |
| | | 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 |
| | | |
| | |
| | | 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: |
| | | |
| | |
| | | # 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. |
| | | |
| | |
| | | |
| | | 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: |
| | | |
| | |
| | | * [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) |
| | |
| | | # Release Policy |
| | | # Release policy |
| | | |
| | | This document defines the release workflow for Ananke. |
| | | |
| | |
| | | * `fix: correct mobile navigation` |
| | | * `docs: update configuration guide` |
| | | |
| | | ## Branching Model |
| | | ## Branching model |
| | | |
| | | ```mermaid |
| | | flowchart LR |
| | |
| | | * Used for testing before release |
| | | * Hosts pre-releases |
| | | |
| | | ### feature branches |
| | | ### Feature branches |
| | | |
| | | * All work must happen in dedicated branches |
| | | * Branch from `development` |
| | |
| | | * `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` |
| | |
| | | * clean history in `main` |
| | | * meaningful commit grouping in `development` |
| | | |
| | | ## Release Types |
| | | ## Release types |
| | | |
| | | ### Pre-releases |
| | | |
| | |
| | | * Tagged as official release |
| | | * Represents stable production state |
| | | |
| | | ## Release Flow: |
| | | ## Release flow |
| | | |
| | | Typical flow: |
| | | |
| | |
| | | } |
| | | |
| | | /* 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; |
| | |
| | | "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", |
| | |
| | | "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", |
| | |
| | | # 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 |
| | | |
| | |
| | | * 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 |
| | |
| | | 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: |