fix: various changes to workspace, testing, linting, etc.

Patrick Kollitsch

8 hours ago c43eae25528e08a19e9bf4af4d5753ab814a1179

fix: various changes to workspace, testing, linting, etc.

 .github/dependabot.yml

@@ -17,7 +17,7 @@
      semver-patch-days: 4
    assignees:
      - davidsneighbour
    target-branch: maintenance
    target-branch: development
    open-pull-requests-limit: 999
    pull-request-branch-name:
      separator: /
@@ -38,7 +38,7 @@
      semver-patch-days: 4
    assignees:
      - davidsneighbour
    target-branch: maintenance
    target-branch: development
    open-pull-requests-limit: 999
    pull-request-branch-name:
      separator: /
@@ -56,7 +56,7 @@
      default-days: 7
    assignees:
      - davidsneighbour
    target-branch: maintenance
    target-branch: development
    open-pull-requests-limit: 999
    pull-request-branch-name:
      separator: /

 .github/workflows/branch-protection.yml

@@ -9,7 +9,7 @@

jobs:
  validate-main-source-branch:
    name: Require staging or maintenance as source branch for main
    name: Require development as source branch for main
    runs-on: ubuntu-latest
    if: github.base_ref == 'main'

@@ -21,53 +21,7 @@
        run: |
          set -euo pipefail

          if [ "${HEAD_REF}" != "staging" ] && [ "${HEAD_REF}" != "maintenance" ]; then
            echo "::error::Pull requests into main must come from staging or maintenance. Current source branch: ${HEAD_REF}"
          if [ "${HEAD_REF}" != "development" ]; then
            echo "::error::Pull requests into main must come from development. Current source branch: ${HEAD_REF}"
            exit 1
          fi

  validate-staging-source-branch:
    name: Require development or maintenance as source branch for staging
    runs-on: ubuntu-latest
    if: github.base_ref == 'staging'

    steps:
      - name: Validate source branch
        shell: bash
        env:
          HEAD_REF: ${{ github.head_ref }}
        run: |
          set -euo pipefail

          if [ "${HEAD_REF}" != "development" ] && [ "${HEAD_REF}" != "maintenance" ]; then
            echo "::error::Pull requests into staging must come from development or maintenance. Current source branch: ${HEAD_REF}"
            exit 1
          fi

  protect-package-lock:
    name: Block package-lock.json outside maintenance
    runs-on: ubuntu-latest
    if: github.base_ref != 'maintenance'

    steps:
      - name: Check out repository
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
        with:
          fetch-depth: 0
          persist-credentials: false

      - name: Fail if package-lock.json changed outside maintenance
        shell: bash
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          BASE_REF: ${{ github.base_ref }}
        run: |
          set -euo pipefail

          changed_files=$(git diff --name-only "${BASE_SHA}...${HEAD_SHA}")

          if echo "${changed_files}" | grep -Fxq "package-lock.json"; then
            echo "::error file=package-lock.json::package-lock.json may only be changed in PRs targeting maintenance. Current target branch: ${BASE_REF}"
            exit 1
          fi

 .markdownlint.jsonc

@@ -1,150 +1,133 @@
{
  "$schema": "https://github.com/DavidAnson/markdownlint/blob/main/schema/markdownlint-config-schema.json",
  "$id": "https://raw.githubusercontent.com/davidsneighbour/kollitsch.dev/refs/heads/main/src/config/.markdownlint.jsonc",
  "default": true,
  "customRules": [
    "@github/markdownlint-github",
    "markdownlint-rule-relative-links",
    "markdownlint-rule-search-replace",
    "markdownlint-rule-extended-ascii",
    "markdownlint-rule-title-case-style",
    "markdownlint-rule-list-duplicates"
  ],
  // Rules
  // unlisted rules are using default settings (usually "true")
  // @see https://github.com/DavidAnson/markdownlint/#rules--aliases
  "MD001": {
    "severity": "error",
    "front_matter_title": "^\\s*title\\s*[:=]"
  },
  "MD003": {
    "style": "atx"
  },
  "MD004": {
    "style": "asterisk"
  },
  "MD005": true,
  "MD007": {
    "indent": 2
  },
  // NO limitation on line length
  "MD013": false,
  // ignored rule for closed atx headings
  "MD020": false,
  // ignored rule for closed atx headings
  "MD021": false,
  // disallow multiple headings with the same content within the same level structure
  "MD024": {
    "siblings_only": true,
    "allow_different_nesting": true
  },
  // no inline HTML elements, except for the allowed ones. in tables only the explicit allowed ones
  "MD033": {
    "allowed_elements": [
      "lite-youtube",
      "color-grid",
      "date-diff",
      "kbd"
    ],
    "table_allowed_elements": [
      "kbd"
    ]
  },
  // use consistent rule markers (`---`)
  "MD035": {
    "style": "---"
  },
  // unused header structure rule
  "MD043": false,
  // unused spelling enforcement
  "MD044": false,
  // fenced code blocks style
  "MD046": {
    "style": "fenced"
  },
  // code blocks must use backticks instead of tildes
  "MD048": {
    "style": "backtick"
  },
  // emphasis must use asterisks `*` instead of underscores `_`
  "MD049": {
    "style": "asterisk"
  },
  // strong style must use double asterisks `**` instead of double underscores `__`
  "MD050": {
    "style": "asterisk"
  },
  // links must not be auto links, all other link formats are allowed
  "MD054": {
    "autolink": false
  },
  // table pipes must be used before and after each table row
  "MD055": {
    "style": "leading_and_trailing"
  },
  // generic linktexts are prohibited
  "MD059": {
    "prohibited_texts": [
      "click here",
      "here",
      "link",
      "more"
    ]
  },
  // table style must be compact (single spaces around cell content)
  "MD060": {
    "style": "aligned"
  },
  // @see https://www.npmjs.com/package/@github/markdownlint-github
  // images should not contain default alternate texts
  "GH001": true,
  // links should not contain generic text ('click here', 'read more', etc.)
  "GH002": {
    "additional_banned_texts": [
      "Something",
      "Click here"
    ]
  },
  // no empty alt texts for images
  "GH003": true,
  // @see https://www.npmjs.com/package/markdownlint-rule-relative-links
  "relative-links": {
    "root_path": "../.."
  },
  // @see https://www.npmjs.com/package/markdownlint-rule-search-replace
  "search-replace": {
    "rules": [
      {
        "name": "ellipsis",
        "message": "Do not use three dots '...' for ellipsis.",
        "information": "https://example.com/rules/ellipsis",
        "search": "...",
        "replace": "…",
        "searchScope": "text"
      },
      {
        "name": "curly-double-quotes",
        "message": "Do not use curly double quotes.",
        "searchPattern": "/“|”/g",
        "replace": "\""
      }
    ]
  },
  // @see https://www.npmjs.com/package/markdownlint-rule-extended-ascii
  "extended-ascii": {
    "ascii-only": true
  },
  // @see https://www.npmjs.com/package/markdownlint-rule-title-case-style
  "title-case-style": {
    // letter case style to apply
    //
    // "sentence" or "title" (default: sentence)
    "case": "sentence",
    // words to ignore when applying letter case.
    //
    // string[] (default: [])
    "ignore": [
      "JavaScript"
    ],
  },
}
    "$schema": "https://github.com/DavidAnson/markdownlint/blob/main/schema/markdownlint-config-schema.json",
    "$id": "https://raw.githubusercontent.com/davidsneighbour/kollitsch.dev/refs/heads/main/src/config/.markdownlint.jsonc",
    "default": true,
    "customRules": [
        "@github/markdownlint-github",
        "markdownlint-rule-relative-links",
        "markdownlint-rule-search-replace",
        "markdownlint-rule-extended-ascii",
        "markdownlint-rule-title-case-style",
        "markdownlint-rule-list-duplicates"
    ],
    // Rules
    // unlisted rules are using default settings (usually "true")
    // @see https://github.com/DavidAnson/markdownlint/#rules--aliases
    "MD001": {
        "severity": "error",
        "front_matter_title": "^\\s*title\\s*[:=]"
    },
    "MD003": {
        "style": "atx"
    },
    "MD004": {
        "style": "asterisk"
    },
    "MD005": true,
    "MD007": {
        "indent": 2
    },
    // NO limitation on line length
    "MD013": false,
    // ignored rule for closed atx headings
    "MD020": false,
    // ignored rule for closed atx headings
    "MD021": false,
    // disallow multiple headings with the same content within the same level structure
    "MD024": {
        "siblings_only": true,
        "allow_different_nesting": true
    },
    // no inline HTML elements, except for the allowed ones. in tables only the explicit allowed ones
    "MD033": {
        "allowed_elements": ["lite-youtube", "color-grid", "date-diff", "kbd"],
        "table_allowed_elements": ["kbd"]
    },
    // use consistent rule markers (`---`)
    "MD035": {
        "style": "---"
    },
    // unused header structure rule
    "MD043": false,
    // unused spelling enforcement
    "MD044": false,
    // fenced code blocks style
    "MD046": {
        "style": "fenced"
    },
    // code blocks must use backticks instead of tildes
    "MD048": {
        "style": "backtick"
    },
    // emphasis must use asterisks `*` instead of underscores `_`
    "MD049": {
        "style": "asterisk"
    },
    // strong style must use double asterisks `**` instead of double underscores `__`
    "MD050": {
        "style": "asterisk"
    },
    // links must not be auto links, all other link formats are allowed
    "MD054": {
        "autolink": false
    },
    // table pipes must be used before and after each table row
    "MD055": {
        "style": "leading_and_trailing"
    },
    // generic linktexts are prohibited
    "MD059": {
        "prohibited_texts": ["click here", "here", "link", "more"]
    },
    // table style must be compact (single spaces around cell content)
    "MD060": {
        "style": "compact"
    },
    // @see https://www.npmjs.com/package/@github/markdownlint-github
    // images should not contain default alternate texts
    "GH001": true,
    // links should not contain generic text ('click here', 'read more', etc.)
    "GH002": {
        "additional_banned_texts": ["Something", "Click here"]
    },
    // no empty alt texts for images
    "GH003": true,
    // @see https://www.npmjs.com/package/markdownlint-rule-relative-links
    "relative-links": {
        "root_path": "../.."
    },
    // @see https://www.npmjs.com/package/markdownlint-rule-search-replace
    "search-replace": {
        "rules": [
            {
                "name": "ellipsis",
                "message": "Do not use three dots '...' for ellipsis.",
                "information": "https://example.com/rules/ellipsis",
                "search": "...",
                "replace": "…",
                "searchScope": "text"
            },
            {
                "name": "curly-double-quotes",
                "message": "Do not use curly double quotes.",
                "searchPattern": "/“|”/g",
                "replace": "\""
            }
        ]
    },
    // @see https://www.npmjs.com/package/markdownlint-rule-extended-ascii
    "extended-ascii": {
        "ascii-only": true
    },
    // @see https://www.npmjs.com/package/markdownlint-rule-title-case-style
    "title-case-style": {
        // letter case style to apply
        //
        // "sentence" or "title" (default: sentence)
        "case": "sentence",
        // words to ignore when applying letter case.
        //
        // string[] (default: [])
        "ignore": ["JavaScript"]
    }
}

 .vscode/extensions.json

File was deleted

 CONTRIBUTING.md

@@ -40,15 +40,15 @@
1. Use a compatible Hugo version (see [`config/_default/module.toml`](https://github.com/gohugo-ananke/ananke/blob/main/config/_default/module.toml) for the current state).
2. Install dependencies:

 ```bash
 npm install
 ```
```bash
npm install
```

1. Run a local preview via `npm run` instead of just calling `hugo server`:

 ```bash
 npm run server
 ```
```bash
npm run server
```

 This runs the documentation site from `site/` using contents from `docs/` with local configuration.

@@ -56,9 +56,9 @@

2. Make sure to install git hooks for linting and testing before you push changes:

 ```bash
 npm run prepare
 ```
```bash
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.

@@ -74,7 +74,6 @@
flowchart LR
 feature["feature/*, fix/*, docs/*, refactor/*"] --> development
 development --> main
 maintenance --> main
 main --> development
```

@@ -82,11 +81,10 @@

### Long-lived branches

| Branch  | Purpose  | Release role | Write policy | Merge  |
| Branch | Purpose | Release role | Write policy | Merge |
| --- | --- | --- | --- | --- |
| `main`  | Stable source of truth | releases | Protected. Only receives reviewed PRs from `staging` or `maintenance`. | Rebase |
| `main` | Stable source of truth | releases | Protected. Only receives reviewed PRs from `development`. | Rebase |
| `development` | Active development | pre-releases | Feature, fix, chore, and documentation PRs target this branch. | Squash |
| `maintenance` | Dependency maintenance  | none | Maintainer-only branch for dependency version updates. | Rebase |

### Branch naming

@@ -98,8 +96,6 @@
* `chore/<topic>`
* `refactor/<topic>`

Dependency update branches MUST target `maintenance` unless the change is part of an intentional feature branch and does not touch lock files.

After a successful rebase between those branches, push with lease:

```bash
@@ -113,9 +109,9 @@
3. Update docs for all user-facing changes.
4. Run quality checks locally:

 ```bash
 npm run lint:markdown
 ```
```bash
npm run lint:markdown
```

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.code-workspace

New file
@@ -0,0 +1,47 @@
{
    "folders": [
        {
            "path": "."
        },
        {
            "path": "../documentation"
        },
        {
            "path": "../template-git-submod"
        },
        {
            "path": "../template-hugo-mod"
        }
    ],
    "settings": {
        "window.autoDetectColorScheme": false,
        "markdown.extension.tableFormatter.enabled": false,
        "chat.tools.terminal.autoApprove": {
            "git fetch": true,
            "git worktree": true,
            "git add": true,
            "git push": true
        }
    },
    "extensions": {
        "recommendations": [
            "ms-vscode.vscode-github-issue-notebooks",
            "github.vscode-pull-request-github",
            "pkief.material-icon-theme",
            "yzhang.markdown-all-in-one",
            "davidanson.vscode-markdownlint",
            "zizmor.zizmor-vscode",
            "redhat.vscode-yaml",
            "streetsidesoftware.code-spell-checker-cspell-bundled-dictionaries",
            "budparr.language-hugo-vscode",
            "jinliming2.vscode-go-template",
            "gohugoio.gotmplfmt",
            "dunstontc.vscode-go-syntax",
            "casualjim.gotemplate",
            "streetsidesoftware.code-spell-checker",
            "streetsidesoftware.code-spell-checker-british-english",
            "gohugoio.gotmplfmt",
            "anthropic.claude-code"
        ]
    }
}

 tests/catalog.yaml

@@ -17,6 +17,14 @@

shortcodes:
  form-contact:
    tests: ["scripts/test-hugo-quickstart.ts"] # TODO: add a dedicated form-contact test
    tests: [
      "scripts/test-hugo-quickstart.ts",
    ] # TODO: add a dedicated form-contact test
  page-index:
    tests: ["scripts/test-hugo-quickstart.ts"] # TODO: add a dedicated page-index test
    tests: [
      "scripts/test-hugo-quickstart.ts",
    ] # TODO: add a dedicated page-index test
  since:
    tests: [
      "scripts/test-hugo-quickstart.ts",
    ] # TODO: add a dedicated since test