Rename format-all to format and add file argument support

.github/workflows/build-test-deploy.yml

@@ -54,7 +54,7 @@ jobs:
           # For repository named username.github.io, use https://username.github.io
           # For other repositories, use https://username.github.io/repository-name
           SITE_URL: ${{ github.event.repository.name == format('{0}.github.io', github.repository_owner) && format('https://{0}.github.io', github.repository_owner) || format('https://{0}.github.io/{1}', github.repository_owner, github.event.repository.name) }}
-        run: yarn run generate-sitemap
+        run: yarn build:sitemap
       - name: Upload build artifact, ready for GitHub Pages deployment
         uses: actions/upload-pages-artifact@v4
         with:

README.md

@@ -45,7 +45,7 @@ Access your site at <http://127.0.0.1:4000> (or see other "server address" in co
 ### Serve/run the site
 
 ```sh
-bundle exec jekyll serve --livereload
+yarn dev
 ```
 
 ### Linting
@@ -59,10 +59,20 @@ yarn lint
 And automatically fix with:
 
 ```sh
-yarn format-all
+yarn format
 ```
 
-**Note:** Prettier caching is enabled using the `cache/` folder to speed up formatting checks. The cache is only written during `--write` operations (not `--check`), so CI environments should not expect cache benefits on lint-only operations.
+You can also run these commands on specific files:
+
+```sh
+yarn lint source/index.html README.md
+yarn format source/index.html README.md
+```
+
+**Notes:**
+- Prettier caching is enabled using the `cache/` folder to speed up formatting checks. The cache is only written during `--write` operations (not `--check`), so CI environments should not expect cache benefits on lint-only operations.
+- Markdown files (`.md`) are formatted by markdownlint, not Prettier (see `.prettierignore`).
+- When you pass specific files, only `.md` files are processed by markdownlint; other file types are silently skipped.
 
 ### Testing
 

package.json

@@ -1,31 +1,55 @@
 {
   "--": [
     "Notes:",
-    "Our scripts use a special POSIX shim that allows you to run i.e. yarn markdownlint-check and specify files to check, or omit the files and it has a default.",
-    "The magic is in the ${@:-\"**/*.md\"} part:",
-    "$@: This represents all the arguments passed to the script (e.g., the files you want to lint).",
-    "${...:-...}: This is the shell's 'use default value' operator.",
-    "In plain English, it means: If $@ (the list of arguments) is empty or not set, use the default value **/*.md. Otherwise, use the arguments that were provided."
+    "",
+    "Script argument handling:",
+    "- Our scripts use a special POSIX shim that allows you to run i.e. yarn lint:markdown and specify files to check, or omit the files and it has a default.",
+    "- The magic is in the ${@:-\"**/*.md\"} part:",
+    "  - $@: This represents all the arguments passed to the script (e.g., the files you want to lint).",
+    "  - ${...:-...}: This is the shell's 'use default value' operator.",
+    "  - In plain English: If $@ (the list of arguments) is empty or not set, use the default value **/*.md. Otherwise, use the arguments that were provided.",
+    "",
+    "Markdown file filtering:",
+    "- lint:markdown and format:markdown only process .md files when specific files are passed.",
+    "- If you run 'yarn format source/index.html README.md', only README.md gets passed to markdownlint.",
+    "- This is necessary because markdownlint-cli2 does not filter by extension - it will attempt to lint any file you explicitly pass to it.",
+    "- The shell loop 'for file in \"$@\"; do case \"$file\" in *.md) ...' implements this filtering.",
+    "",
+    "Prettier ignore behavior:",
+    "- Prettier respects .prettierignore even when you pass specific file paths.",
+    "- .prettierignore contains '*.md' so Prettier silently skips Markdown files.",
+    "- This means 'yarn format README.md' will skip Prettier but run markdownlint on README.md.",
+    "- This is intentional: we want markdownlint (not Prettier) to format Markdown files.",
+    "",
+    "Known issues:",
+    "- yarn test:html-validate returns exit code 129 when run through yarn, despite tests passing.",
+    "- This appears to be related to how Yarn Berry handles worker_threads termination.",
+    "- Workaround: run tests individually or use CI/CD which may handle this differently.",
+    "- The tests themselves pass correctly (see output), only the exit code is affected."
   ],
   "license": "UNLICENSED",
   "devDependencies": {
-    "@fulldecent/nice-checkers-plugin": "^1.2.0",
+    "@fulldecent/nice-checkers-plugin": "^1.2.1",
     "@shopify/prettier-plugin-liquid": "^1.10.0",
     "cheerio": "^1.1.2",
     "css": "^3.0.0",
     "glob": "^13.0.0",
     "html-validate": "^10.4.0",
-    "markdownlint-cli2": "^0.19.1",
+    "markdownlint-cli2": "^0.20.0",
     "prettier": "^3.7.4"
   },
   "scripts": {
     "lint": "sh -c 'yarn lint:prettier \"$@\" && yarn lint:markdown \"$@\"' --",
     "lint:prettier": "sh -c 'yarn prettier --cache --cache-location=cache/.prettiercache --check ${@:-\".\"}' --",
-    "lint:markdown": "sh -c 'yarn markdownlint-cli2 ${@:-\"**/*.md\"}' --",
-    "format-all": "yarn prettier --cache --cache-location=cache/.prettiercache --write . && yarn markdownlint-cli2 --fix '**/*.md'",
-    "build": "bundle exec jekyll build",
-    "generate-sitemap": "node scripts/generate-sitemap.mjs",
-    "test": "sh -c 'yarn test:html-validate \"$@\" && yarn test:dirty-file-paths-checker \"$@\" && yarn test:unused-assets' --",
+    "lint:markdown": "sh -c 'if [ $# -eq 0 ]; then yarn markdownlint-cli2 \"**/*.md\"; else for file in \"$@\"; do case \"$file\" in *.md) yarn markdownlint-cli2 \"$file\";; esac; done; fi' --",
+    "format": "sh -c 'yarn format:prettier \"$@\" && yarn format:markdown \"$@\"' --",
+    "format:prettier": "sh -c 'yarn prettier --cache --cache-location=cache/.prettiercache --write ${@:-\".\"}' --",
+    "format:markdown": "sh -c 'if [ $# -eq 0 ]; then yarn markdownlint-cli2 --fix \"**/*.md\"; else for file in \"$@\"; do case \"$file\" in *.md) yarn markdownlint-cli2 --fix \"$file\";; esac; done; fi' --",
+    "dev": "bundle exec jekyll serve --livereload",
+    "build": "yarn build:jekyll && yarn build:sitemap",
+    "build:jekyll": "bundle exec jekyll build",
+    "build:sitemap": "node scripts/generate-sitemap.mjs",
+    "test": "sh -c 'yarn test:html-validate \"$@\" && yarn test:dirty-file-paths-checker && yarn test:unused-assets' --",
     "test:html-validate": "node test/html-validate.mjs",
     "test:dirty-file-paths-checker": "node test/dirty-file-paths-checker.mjs",
     "test:unused-assets": "node test/unused-assets.mjs",

yarn.lock

@@ -5,15 +5,16 @@ __metadata:
   version: 8
   cacheKey: 10c0
 
-"@fulldecent/nice-checkers-plugin@npm:^1.2.0":
-  version: 1.2.0
-  resolution: "@fulldecent/nice-checkers-plugin@npm:1.2.0"
+"@fulldecent/nice-checkers-plugin@npm:^1.2.1":
+  version: 1.2.1
+  resolution: "@fulldecent/nice-checkers-plugin@npm:1.2.1"
   dependencies:
     better-sqlite3: "npm:^12.5.0"
+    cheerio: "npm:^1.1.2"
     shell-quote: "npm:^1.8.3"
   peerDependencies:
     html-validate: ^10.0.0
-  checksum: 10c0/d0249c4547a3249e5ca5c008c0f42041f3132f21827b731fa2aad5bb4fc69f776c014a2845d3c228ff07baf038ab97858e87a6d420e00714d748048ca5420fa5
+  checksum: 10c0/fa5d2a12a8d44cbe39fe9da496b372749cba602bb33815a6958dd280c27e4e604e8adc09d0b9440ebd998a65c1514e78d08d52b06230b29182e6cfb2eb19afd3
   languageName: node
   linkType: hard
 
@@ -839,6 +840,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"get-east-asian-width@npm:^1.3.0":
+  version: 1.4.0
+  resolution: "get-east-asian-width@npm:1.4.0"
+  checksum: 10c0/4e481d418e5a32061c36fbb90d1b225a254cc5b2df5f0b25da215dcd335a3c111f0c2023ffda43140727a9cafb62dac41d022da82c08f31083ee89f714ee3b83
+  languageName: node
+  linkType: hard
+
 "github-from-package@npm:0.0.0":
   version: 0.0.0
   resolution: "github-from-package@npm:0.0.0"
@@ -1325,26 +1333,26 @@ __metadata:
   languageName: node
   linkType: hard
 
-"markdownlint-cli2@npm:^0.19.1":
-  version: 0.19.1
-  resolution: "markdownlint-cli2@npm:0.19.1"
+"markdownlint-cli2@npm:^0.20.0":
+  version: 0.20.0
+  resolution: "markdownlint-cli2@npm:0.20.0"
   dependencies:
     globby: "npm:15.0.0"
     js-yaml: "npm:4.1.1"
     jsonc-parser: "npm:3.3.1"
     markdown-it: "npm:14.1.0"
-    markdownlint: "npm:0.39.0"
+    markdownlint: "npm:0.40.0"
     markdownlint-cli2-formatter-default: "npm:0.0.6"
     micromatch: "npm:4.0.8"
   bin:
     markdownlint-cli2: markdownlint-cli2-bin.mjs
-  checksum: 10c0/fdac00f87a0a4ad155a332f5926d6ce4be153f4fac0362722d9620821bb638f2def29991ede102d245975a62084323f1a3032dfc4f39f17899b38f11f79619e5
+  checksum: 10c0/6c5dfc16b93db4adb39a890a745e71eda91e43e0abbd3e70f9f96057bf2c07de9df982c0be2868be170dbfa59e162c9b8632849096a177cf164f9dbd9c5f67b4
   languageName: node
   linkType: hard
 
-"markdownlint@npm:0.39.0":
-  version: 0.39.0
-  resolution: "markdownlint@npm:0.39.0"
+"markdownlint@npm:0.40.0":
+  version: 0.40.0
+  resolution: "markdownlint@npm:0.40.0"
   dependencies:
     micromark: "npm:4.0.2"
     micromark-core-commonmark: "npm:2.0.3"
@@ -1354,7 +1362,8 @@ __metadata:
     micromark-extension-gfm-table: "npm:2.1.1"
     micromark-extension-math: "npm:3.1.0"
     micromark-util-types: "npm:2.0.2"
-  checksum: 10c0/aaa079902fa1585e3769a0f699478cdcca0e2bf205916e5cc90a362746548b5530aa8e0a762e255b5e05dc481d86f9e8859780d4e5943e3ace8a5fb48023b6af
+    string-width: "npm:8.1.0"
+  checksum: 10c0/1543fcf4a433bc54e0e565cb1c8111e5e3d0df3742df0cc840d470bced21a1e3b5593e4e380ad0d8d5e490d9b399699d48aeabed33719f3fbdc6d00128138f20
   languageName: node
   linkType: hard
 
@@ -2167,14 +2176,14 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "root-workspace-0b6124@workspace:."
   dependencies:
-    "@fulldecent/nice-checkers-plugin": "npm:^1.2.0"
+    "@fulldecent/nice-checkers-plugin": "npm:^1.2.1"
     "@shopify/prettier-plugin-liquid": "npm:^1.10.0"
     cheerio: "npm:^1.1.2"
     css: "npm:^3.0.0"
     front-matter: "npm:^4.0.2"
     glob: "npm:^13.0.0"
     html-validate: "npm:^10.4.0"
-    markdownlint-cli2: "npm:^0.19.1"
+    markdownlint-cli2: "npm:^0.20.0"
     prettier: "npm:^3.7.4"
     xml2js: "npm:^0.6.2"
   dependenciesMeta:
@@ -2363,6 +2372,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"string-width@npm:8.1.0":
+  version: 8.1.0
+  resolution: "string-width@npm:8.1.0"
+  dependencies:
+    get-east-asian-width: "npm:^1.3.0"
+    strip-ansi: "npm:^7.1.0"
+  checksum: 10c0/749b5d0dab2532b4b6b801064230f4da850f57b3891287023117ab63a464ad79dd208f42f793458f48f3ad121fe2e1f01dd525ff27ead957ed9f205e27406593
+  languageName: node
+  linkType: hard
+
 "string-width@npm:^5.0.1, string-width@npm:^5.1.2":
   version: 5.1.2
   resolution: "string-width@npm:5.1.2"
@@ -2401,6 +2420,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"strip-ansi@npm:^7.1.0":
+  version: 7.1.2
+  resolution: "strip-ansi@npm:7.1.2"
+  dependencies:
+    ansi-regex: "npm:^6.0.1"
+  checksum: 10c0/0d6d7a023de33368fd042aab0bf48f4f4077abdfd60e5393e73c7c411e85e1b3a83507c11af2e656188511475776215df9ca589b4da2295c9455cc399ce1858b
+  languageName: node
+  linkType: hard
+
 "strip-json-comments@npm:~2.0.1":
   version: 2.0.1
   resolution: "strip-json-comments@npm:2.0.1"