From 531e780e580a315d7f4808bc033f592a71362b75 Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 13:24:01 -0500 Subject: [PATCH 01/15] Adds lint.yaml with linting instructions for changed MD files --- .github/workflows/lint.yaml | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 .github/workflows/lint.yaml diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml new file mode 100644 index 0000000..99a2e68 --- /dev/null +++ b/.github/workflows/lint.yaml @@ -0,0 +1,31 @@ +name: Linting + +on: + push: + branches: + - main + pull_request: + branches: + - main + +jobs: + lint: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v6 + with: + fetch-depth: 0 + + # This identifies which files changed in the specific commit or PR + - uses: tj-actions/changed-files@v47 + id: changed-files + with: + files: '**/*.md' + separator: "," + + # This runs the linter ONLY on the files identified above + - uses: DavidAnson/markdownlint-cli2-action@v22 + if: steps.changed-files.outputs.any_changed == 'true' + with: + globs: ${{ steps.changed-files.outputs.all_changed_files }} + separator: "," \ No newline at end of file From 69719b32da08cde01651c3fba822ace28ac39943 Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 13:33:08 -0500 Subject: [PATCH 02/15] Updates contributing.md with automated linting information --- CONTRIBUTING.md | 21 ++++++++++++++++----- 1 file changed, 16 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4cff87..1d59074 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -177,7 +177,12 @@ chore: update mkdocs dependencies ### Linting -The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. Key settings: +The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. + +**Automated Checks:** +We have a GitHub Action that checks for formatting errors on Pull Requests. To avoid flagging legacy issues, **it only checks files that you have modified.** + +**Key Rules:** - 4-space indentation for lists (`MD007`). - No hard tab restrictions disabled. @@ -186,13 +191,19 @@ The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with - Allowed code blocks without language specification (`MD040`). - Allow fenced code blocks, as this commonly errors when indented (see [discussion](https://github.com/DavidAnson/markdownlint/issues/327)). -For faster PR review, you may want to run linting locally; we do have a PR Action in place as well. First install markdownlint, then run +**Local Testing** +For faster PR review, you may want to run linting locally. We recommend installing `markdownlint-cli2` or the VS Code extension. -```console -markdownlint -c .markdownlint.json -f docs/wiki-guide/ +```bash +# Install +npm install markdownlint-cli2 --global +# Run on the specific file you are editing +markdownlint-cli2 "docs/path/to/your/file.md" +# Fix simple errors automatically +markdownlint-cli2 --fix "docs/path/to/your/file.md" ``` -The `-f` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`). +The `--fix` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`). ### Content Review From cda392143d4fe851093de80d1fe118e3766d6635 Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 13:43:57 -0500 Subject: [PATCH 03/15] test: add bad markdown to verify linter failure --- lint-fail-test.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 lint-fail-test.md diff --git a/lint-fail-test.md b/lint-fail-test.md new file mode 100644 index 0000000..795d48b --- /dev/null +++ b/lint-fail-test.md @@ -0,0 +1,13 @@ +# Invalid Header with Punctuation. + +#BadHeader formatting (No space after hash) + +* Level 1 item + * Level 2 item (This uses 2 spaces, but your config demands 4) + +This line has trailing spaces at the end. + +
+ + +(The blank lines above violate MD012) \ No newline at end of file From 2152882f3a90d08fc1e589aa3911e759461b0579 Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 13:54:31 -0500 Subject: [PATCH 04/15] test: remove bad markdown file used for testing --- lint-fail-test.md | 13 ------------- 1 file changed, 13 deletions(-) delete mode 100644 lint-fail-test.md diff --git a/lint-fail-test.md b/lint-fail-test.md deleted file mode 100644 index 795d48b..0000000 --- a/lint-fail-test.md +++ /dev/null @@ -1,13 +0,0 @@ -# Invalid Header with Punctuation. - -#BadHeader formatting (No space after hash) - -* Level 1 item - * Level 2 item (This uses 2 spaces, but your config demands 4) - -This line has trailing spaces at the end. - -
- - -(The blank lines above violate MD012) \ No newline at end of file From 33ec57ccababfd730a3af66fb3db2d0a63042f5b Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 15:20:15 -0500 Subject: [PATCH 05/15] Implements -f in action to auto-fix small md errors --- .github/workflows/lint.yaml | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index 99a2e68..63c2c48 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -8,6 +8,9 @@ on: branches: - main +permissions: + contents: write + jobs: lint: runs-on: ubuntu-latest @@ -28,4 +31,20 @@ jobs: if: steps.changed-files.outputs.any_changed == 'true' with: globs: ${{ steps.changed-files.outputs.all_changed_files }} - separator: "," \ No newline at end of file + separator: "," + fix: true + + # Check if anything was fixed, then Commit & Push + - name: Commit and push fixes + if: always() && steps.changed-files.outputs.any_changed == 'true' + run: | + # Configure the bot's identity + git config --global user.name "github-actions[bot]" + git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" + + # Check if the linter modified any files + if [[ -n $(git status -s) ]]; then + git add . + git commit -m "style: auto-fix markdown formatting" + git push + fi \ No newline at end of file From f1a233f1e4905aabb97fd8d6ae736780fa6cc9c6 Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 15:23:20 -0500 Subject: [PATCH 06/15] test: add bad markdown to verify auto-fixes --- lint-fail-test.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) create mode 100644 lint-fail-test.md diff --git a/lint-fail-test.md b/lint-fail-test.md new file mode 100644 index 0000000..92a6052 --- /dev/null +++ b/lint-fail-test.md @@ -0,0 +1,13 @@ +#Auto-Fixable Header (No space after hash) + +This paragraph has trailing spaces at the end. + +# Duplicate Header +Content A + +# Duplicate Header +Content B (Linter won't be able to fix the duplicate header but should point it out) + +
+ Inline HTML is also not auto-fixable +
\ No newline at end of file From 07de5c40550fc5697211347308a1906a5fcd360f Mon Sep 17 00:00:00 2001 From: emersonfras Date: Wed, 10 Dec 2025 15:26:08 -0500 Subject: [PATCH 07/15] Explicitly push HEAD to the PR branch for auto-fixes --- .github/workflows/lint.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index 63c2c48..b8355c6 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -46,5 +46,5 @@ jobs: if [[ -n $(git status -s) ]]; then git add . git commit -m "style: auto-fix markdown formatting" - git push + git push origin HEAD:${{ github.head_ref }} fi \ No newline at end of file From bc39e0873c07c0ace9a92da82a204dfb70d94d68 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Wed, 10 Dec 2025 20:26:22 +0000 Subject: [PATCH 08/15] style: auto-fix markdown formatting --- lint-fail-test.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/lint-fail-test.md b/lint-fail-test.md index 92a6052..1810016 100644 --- a/lint-fail-test.md +++ b/lint-fail-test.md @@ -1,13 +1,15 @@ -#Auto-Fixable Header (No space after hash) +# Auto-Fixable Header (No space after hash) -This paragraph has trailing spaces at the end. +This paragraph has trailing spaces at the end. # Duplicate Header + Content A # Duplicate Header + Content B (Linter won't be able to fix the duplicate header but should point it out)
Inline HTML is also not auto-fixable -
\ No newline at end of file + From c83003f91edf6a2518289935891a7c3fc8d5454e Mon Sep 17 00:00:00 2001 From: emersonfras Date: Fri, 12 Dec 2025 14:13:28 -0500 Subject: [PATCH 09/15] Clarification on automated checks and legacy issues --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1d59074..f425f73 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,7 +180,7 @@ chore: update mkdocs dependencies The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. **Automated Checks:** -We have a GitHub Action that checks for formatting errors on Pull Requests. To avoid flagging legacy issues, **it only checks files that you have modified.** +We have a GitHub Action that checks for formatting errors on Pull Requests. To follow best practices, **it only checks files that you have modified.** **Key Rules:** From ee109e51bdd0115c5e84f5f06639d2c7b77bb79a Mon Sep 17 00:00:00 2001 From: emersonfras Date: Fri, 12 Dec 2025 14:15:33 -0500 Subject: [PATCH 10/15] Revert markdownlint-cli2 back to markdownlint for local testing --- CONTRIBUTING.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f425f73..c3037e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -194,16 +194,11 @@ We have a GitHub Action that checks for formatting errors on Pull Requests. To f **Local Testing** For faster PR review, you may want to run linting locally. We recommend installing `markdownlint-cli2` or the VS Code extension. -```bash -# Install -npm install markdownlint-cli2 --global -# Run on the specific file you are editing -markdownlint-cli2 "docs/path/to/your/file.md" -# Fix simple errors automatically -markdownlint-cli2 --fix "docs/path/to/your/file.md" +```console +markdownlint -c .markdownlint.json -f docs/wiki-guide/ ``` -The `--fix` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`). +The `-f` resolves simple formatting issues, and alerts will be raised for more complicated linter style rules (e.g., referencing a link as `[here](URL)` will produce the line: `.md:191:2 MD059/descriptive-link-text Link text should be descriptive [Context: "[here]"]`). ### Content Review From fab4aeb605066721fea96dd61b63620e22d0162d Mon Sep 17 00:00:00 2001 From: emersonfras Date: Fri, 12 Dec 2025 14:16:47 -0500 Subject: [PATCH 11/15] Revert automated workflow lint fixing --- .github/workflows/lint.yaml | 19 ------------------- 1 file changed, 19 deletions(-) diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml index b8355c6..d439c69 100644 --- a/.github/workflows/lint.yaml +++ b/.github/workflows/lint.yaml @@ -8,9 +8,6 @@ on: branches: - main -permissions: - contents: write - jobs: lint: runs-on: ubuntu-latest @@ -32,19 +29,3 @@ jobs: with: globs: ${{ steps.changed-files.outputs.all_changed_files }} separator: "," - fix: true - - # Check if anything was fixed, then Commit & Push - - name: Commit and push fixes - if: always() && steps.changed-files.outputs.any_changed == 'true' - run: | - # Configure the bot's identity - git config --global user.name "github-actions[bot]" - git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com" - - # Check if the linter modified any files - if [[ -n $(git status -s) ]]; then - git add . - git commit -m "style: auto-fix markdown formatting" - git push origin HEAD:${{ github.head_ref }} - fi \ No newline at end of file From c17b1e82c9d3306786156c14939b29af110912d9 Mon Sep 17 00:00:00 2001 From: emersonfras Date: Fri, 12 Dec 2025 14:22:52 -0500 Subject: [PATCH 12/15] test: Remove lint-fail-test.md --- lint-fail-test.md | 15 --------------- 1 file changed, 15 deletions(-) delete mode 100644 lint-fail-test.md diff --git a/lint-fail-test.md b/lint-fail-test.md deleted file mode 100644 index 1810016..0000000 --- a/lint-fail-test.md +++ /dev/null @@ -1,15 +0,0 @@ -# Auto-Fixable Header (No space after hash) - -This paragraph has trailing spaces at the end. - -# Duplicate Header - -Content A - -# Duplicate Header - -Content B (Linter won't be able to fix the duplicate header but should point it out) - -
- Inline HTML is also not auto-fixable -
From a414bcd39814c5356730800733d90e3d9995b7be Mon Sep 17 00:00:00 2001 From: emersonfras Date: Fri, 12 Dec 2025 14:25:17 -0500 Subject: [PATCH 13/15] Fix linter name in local testing section --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c3037e2..dba6bb8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,7 +192,7 @@ We have a GitHub Action that checks for formatting errors on Pull Requests. To f - Allow fenced code blocks, as this commonly errors when indented (see [discussion](https://github.com/DavidAnson/markdownlint/issues/327)). **Local Testing** -For faster PR review, you may want to run linting locally. We recommend installing `markdownlint-cli2` or the VS Code extension. +For faster PR review, you may want to run linting locally. We recommend installing `markdownlint-cli` or the VS Code extension. ```console markdownlint -c .markdownlint.json -f docs/wiki-guide/ From ad25ccf1ad50e5e791ec37841f32bdf73cca39ea Mon Sep 17 00:00:00 2001 From: emersonfras Date: Fri, 12 Dec 2025 14:28:24 -0500 Subject: [PATCH 14/15] Instructions to check details for automated check fail --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dba6bb8..e2d467d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -180,7 +180,7 @@ chore: update mkdocs dependencies The project uses [markdownlint](https://github.com/DavidAnson/markdownlint) with configuration in `.markdownlint.json`. **Automated Checks:** -We have a GitHub Action that checks for formatting errors on Pull Requests. To follow best practices, **it only checks files that you have modified.** +We have a GitHub Action that checks for formatting errors on Pull Requests. To follow best practices, **it only checks files that you have modified.** If the check fails, click the **Details** link next to the status check to view the error logs and see exactly what needs fixing. **Key Rules:** From f47864b3ae8c8ec91d815bde229aabc8db971fbf Mon Sep 17 00:00:00 2001 From: Emerson Frasure Date: Tue, 16 Dec 2025 14:06:09 -0500 Subject: [PATCH 15/15] Update CONTRIBUTING.md to include lint URLs Co-authored-by: Elizabeth Campolongo <38985481+egrace479@users.noreply.github.com> --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e2d467d..d3dda47 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -192,7 +192,7 @@ We have a GitHub Action that checks for formatting errors on Pull Requests. To f - Allow fenced code blocks, as this commonly errors when indented (see [discussion](https://github.com/DavidAnson/markdownlint/issues/327)). **Local Testing** -For faster PR review, you may want to run linting locally. We recommend installing `markdownlint-cli` or the VS Code extension. +For faster PR review, you may want to run linting locally. We recommend installing [`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli) or the [VS Code extension](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint). ```console markdownlint -c .markdownlint.json -f docs/wiki-guide/