Skip to content

feat: Add markdown linting with markdownlint-cli2 #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yacosta738 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: Add markdown linting with markdownlint-cli2 #193

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions .github/workflows/markdownlint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
name: Markdown Lint

on:
pull_request:
paths:
- "**/*.md"
- "**/*.mdx"

jobs:
markdownlint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: 🧩 Setup Node.js and pnpm
uses: ./.github/actions/setup/node
with:
node-version: "22"
- run: pnpm install
- run: npx markdownlint-cli2 "**/*.md" "**/*.mdx"
Comment on lines +18 to +19
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Use the package script or pnpm exec for consistency and version pinning.

Avoid npx fetching a different version at runtime. Reuse the script or invoke via pnpm exec.

Apply one of:

-      - run: pnpm install
-      - run: npx markdownlint-cli2 "**/*.md" "**/*.mdx"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint:md

or

-      - run: pnpm install
-      - run: npx markdownlint-cli2 "**/*.md" "**/*.mdx"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm exec markdownlint-cli2 "**/*.md" "**/*.mdx"

Also, confirm the local action ./.github/actions/setup/node supports Node 22 and sets up pnpm caching; if not, consider using actions/setup-node with pnpm/action-setup and a cache key on pnpm-store.

🏁 Script executed:

#!/bin/bash
set -e

echo "1. Searching for 'lint:md' script in package.json"
rg -n '"lint:md"' -g 'package.json' || echo "→ No 'lint:md' script found in package.json"

echo
echo "2. Searching for 'markdownlint-cli2' mentions in package.json scripts"
rg -n '"markdownlint-cli2"' -g 'package.json' || echo "→ No direct 'markdownlint-cli2' script found"

echo
echo "3. Inspecting .github/workflows/markdownlint.yml for setup actions"
rg -n 'uses:' -C1 .github/workflows/markdownlint.yml || echo "→ No 'uses:' lines found in workflow"

echo
echo "4. Listing local GitHub Actions under .github/actions"
find .github/actions -maxdepth 3 -type f -print || echo "→ No local actions directory found"

Length of output: 1414

🏁 Script executed:

#!/bin/bash
set -e

echo "Inspecting .github/actions/setup/node/action.yml"
sed -n '1,200p' .github/actions/setup/node/action.yml || echo "→ Unable to read action.yml"

Length of output: 2470

🏁 Script executed:

#!/bin/bash
set -e

echo "Displaying .github/workflows/markdownlint.yml (lines 1–200):"
sed -n '1,200p' .github/workflows/markdownlint.yml || echo "→ Unable to read workflow file"

Length of output: 582

Update Markdown workflow to use frozen lockfile and existing lint script

For reproducible installs and pinned linting, replace the install and npx steps with your package script:

• File: .github/workflows/markdownlint.yml
Replace lines 18–19:

-      - run: pnpm install
-      - run: npx markdownlint-cli2 "**/*.md" "**/*.mdx"
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm run lint:md

The local .github/actions/setup/node action already pins Node 22 and configures pnpm caching, so no changes are needed there.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- run: pnpm install
- run: npx markdownlint-cli2 "**/*.md" "**/*.mdx"
- run: pnpm install --frozen-lockfile
- run: pnpm run lint:md
🤖 Prompt for AI Agents 
.github/workflows/markdownlint.yml around lines 18 to 19: replace the two steps
that run "pnpm install" and "npx markdownlint-cli2 ..." with a single step that
first installs using a frozen lockfile and then invokes the repository's
markdown lint script (for example: run "pnpm install --frozen-lockfile && pnpm
run lint:markdown"), so installs are reproducible and the linting uses the
pinned script from package.json.

6 changes: 6 additions & 0 deletions .markdownlint.jsonc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"default": true,
"MD013": false,
Copy link

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The configuration disables MD033 (no-inline-html) rule but the PR description mentions disabling 'no-bare-urls' rule. Consider adding a comment explaining why MD033 is disabled or verify if this matches the intended configuration.

Suggested change
"MD013": false,
"MD013": false,
// MD033 (no-inline-html) is disabled to allow inline HTML in markdown files as required by our documentation style.

Copilot uses AI. Check for mistakes.
"MD033": false,
Copy link

Copilot AI Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The MD041 rule (first-line-heading/first-line-h1) is disabled but not mentioned in the PR description. Consider documenting why this rule is disabled for better maintainability.

Suggested change
"MD033": false,
"MD033": false,
// MD041 (first-line-heading/first-line-h1) is disabled to allow Markdown files without a top-level heading, as per project documentation conventions.

Copilot uses AI. Check for mistakes.
"MD041": false
}
Comment on lines +1 to +6
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Fix rules to match PR intent (no-bare-urls + asterisk emphasis) and avoid over-disabling.

Current config disables MD033 (no-inline-html) and MD041 (first heading) but PR objectives call for disabling MD034 (no-bare-urls) and setting emphasis style to asterisk. Recommend correcting the rules and adding MD049 configuration.

Apply this diff:

 {
   "default": true,
   "MD013": false,
-  "MD033": false,
-  "MD041": false
+  "MD034": false,
+  "MD049": { "style": "asterisk" }
 }

If disabling MD041 was intentional for your docs, keep it alongside the above as needed.

🏁 Script executed:

#!/bin/bash
# Display the current markdownlint config to verify disabled rules
cat .markdownlint.jsonc

Length of output: 97

Align markdownlint rules with PR objectives
The current config disables MD033 (inline HTML) and MD041 (first-heading), but the PR intends to disable MD034 (no-bare-urls) and enforce asterisk-based emphasis. Update the config accordingly:

  • Remove "MD033": false
  • Add "MD034": false
  • Add "MD049": { "style": "asterisk" }
  • Retain "MD041": false if you still want to disable the first-heading rule
 {
   "default": true,
   "MD013": false,
-  "MD033": false,
+  "MD034": false,
+  "MD049": { "style": "asterisk" },
   "MD041": false
 }
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
{
"default": true,
"MD013": false,
"MD033": false,
"MD041": false
}
{
"default": true,
"MD013": false,
"MD034": false,
"MD049": { "style": "asterisk" },
"MD041": false
}
🤖 Prompt for AI Agents 
.markdownlint.jsonc around lines 1 to 6: the current config disables MD033 and
MD041 but the PR intends to disable MD034 and enforce asterisk emphasis; remove
the "MD033": false entry, add "MD034": false, add "MD049": { "style": "asterisk"
}, and keep "MD041": false if you still want to disable the first-heading rule
so the file reflects the PR objectives.

4 changes: 4 additions & 0 deletions lefthook.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,11 @@
# @ref https://evilmartians.github.io/lefthook/

pre-commit:
parallel: true
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Avoid running pre-commit commands in parallel due to race conditions with file-modifying hooks.

With parallel: true, commands like ruler:apply and git update-index can race with others, leading to nondeterministic results and staged content drift. Order also cannot be guaranteed in parallel mode (contradicts “placed before” intent).

Apply this diff to run hooks sequentially:

 pre-commit:
-  parallel: true
+  parallel: false
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
parallel: true
pre-commit:
parallel: false
🤖 Prompt for AI Agents 
In lefthook.yml around line 5, the file enables parallel execution ("parallel:
true") which can cause race conditions for file-modifying pre-commit hooks;
change this to run hooks sequentially by removing the "parallel: true" entry or
setting it to "parallel: false", then verify that hooks which modify files
(e.g., ruler:apply, any git update-index usage) are ordered before validation
hooks so their changes are staged before subsequent checks.

commands:
markdownlint:
glob: "**/*.{md,mdx}"
run: npx markdownlint-cli2 {staged_files}
Comment on lines +7 to +9
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Use pnpm exec (or npx --no-install) for deterministic local tool usage.

npx without --no-install may fetch arbitrary remote versions. Prefer pnpm exec to use the repo-pinned version. Also keeps behavior consistent with other hooks (e.g., commitlint uses --no-install).

Apply this diff:

     markdownlint:
       glob: "**/*.{md,mdx}"
-      run: npx markdownlint-cli2 {staged_files}
+      run: pnpm exec markdownlint-cli2 {staged_files}

Note: {staged_files} expands to a space-separated list; filenames with spaces could be problematic. If your repo allows such filenames, consider a wrapper script to safely handle arguments or lint via globs and restrict to staged via lefthook’s file list piping.

🏁 Script executed:

#!/bin/bash
# Verify that pnpm is the package manager (pnpm-lock.yaml exists)
echo "=== Checking for pnpm-lock.yaml ==="
fd pnpm-lock.yaml || echo "pnpm-lock.yaml not found"

echo ""
# Show lefthook.yml entries for markdownlint and commitlint
echo "=== Extracting markdownlint and commitlint hooks from lefthook.yml ==="
rg -n 'markdownlint:|commitlint:' -C3 -t yml lefthook.yml || echo "No matches found"

Length of output: 408

🏁 Script executed:

#!/bin/bash
# Extract markdownlint and commitlint sections from lefthook.yml
echo "=== Lefthook: markdownlint hook ==="
rg -n 'markdownlint:' -C5 lefthook.yml || echo "✗ markdownlint section not found"

echo ""
echo "=== Lefthook: commitlint hook ==="
rg -n 'commitlint:' -C5 lefthook.yml || echo "✗ commitlint section not found"

echo ""
# Check for any filenames with spaces in the repo
echo "=== Checking for files with spaces in their names ==="
find . -not -path "./.git/*" -type f -name "* *" | head -n 5 || echo "✓ No files with spaces found (up to 5 shown)"

Length of output: 830

Use pnpm exec for deterministic local tool usage

  • Confirmed this repo uses pnpm (pnpm-lock.yaml is present).
  • No files with spaces were found in the current tree, so {staged_files} expansion is safe.

Apply this change in lefthook.yml:

     markdownlint:
       glob: "**/*.{md,mdx}"
-      run: npx markdownlint-cli2 {staged_files}
+      run: pnpm exec markdownlint-cli2 {staged_files}
🤖 Prompt for AI Agents 
In lefthook.yml around lines 7 to 9, the pre-commit hook uses npx which is
non-deterministic for a pnpm-based repo; replace the command "npx
markdownlint-cli2 {staged_files}" with a pnpm-based invocation such as "pnpm
exec markdownlint-cli2 -- {staged_files}" so the repo uses pnpm for
deterministic local tool execution; update the single line in the markdownlint
hook accordingly and keep the glob as-is.

generate_structure_docs:
run: ./scripts/generate-structure-docs.sh
biome:
Expand Down
10 changes: 9 additions & 1 deletion package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@
"test:ui": "pnpm --recursive run test:ui",
"test:coverage": "pnpm --recursive run test:coverage",
"lint": "pnpm --recursive --parallel run lint",
"lint:md": "markdownlint-cli2 \"**/*.md\" \"**/*.mdx\"",
Copy link
Contributor

@coderabbitai coderabbitai bot Aug 16, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick (assertive)

Deduplicate command definitions across CI and hooks by reusing the script.

Both the workflow and pre-commit hook shell out to markdownlint-cli2 with the same globs. Prefer a single source of truth to avoid drift.

  • In the workflow: replace the markdownlint step with pnpm run lint:md.
  • In the pre-commit hook: replace the run command with pnpm run -s lint:md -- {staged_files} if you stick with staged files; or keep pnpm exec but then ensure globs stay aligned with this script.

I can push a patch across files if you prefer.

🤖 Prompt for AI Agents 
package.json around line 54: the markdownlint-cli2 invocation is duplicated in
CI workflow and the pre-commit hook; update CI to call the new script (pnpm run
lint:md) instead of invoking markdownlint-cli2 directly, and update the
pre-commit hook to call pnpm run -s lint:md -- {staged_files} (or if you prefer
pnpm exec keep the same globs but ensure they exactly match the script) so both
CI and hooks reuse the single lint:md script and avoid drift.

"lint:strict": "pnpm --recursive --parallel run lint:strict",
"check": "pnpm run -r check && biome check . --write",
"clean": "pnpm --recursive run clean",
Expand All @@ -70,10 +71,17 @@
"@commitlint/cli": "^19.8.1",
"@commitlint/config-conventional": "^19.8.1",
"lefthook": "^1.12.2",
"markdownlint-cli2": "^0.18.1",
"npm-run-all2": "^8.0.4",
"rimraf": "^6.0.1",
"tree-extended": "^4.6.0",
"vite": "^7.0.6",
"vitest": "^3.2.4"
"vitest": "^3.2.4",
"@types/node": "22.17.2"
},
"pnpm": {
"overrides": {
"@types/node": "22.17.2"
}
}
}
Loading
Loading