feat: Add markdown linting with markdownlint-cli2 #193
Conversation
This commit introduces markdown linting to the project using `markdownlint-cli2`. It includes the following: - A new dev dependency on `markdownlint-cli2`. - A `.markdownlint.jsonc` configuration file in the root, which disables the `line-length` and `no-bare-urls` rules and sets the emphasis style to `asterisk`. - A `lint:md` script in the root `package.json` for manual linting. - A `lefthook` pre-commit hook that runs the linter on staged `.md` and `.mdx` files. - A new GitHub Action workflow in `.github/workflows/markdownlint.yml` that runs the linter on all pull requests. Additionally, this commit includes a fix for the project's dependencies. The build was failing due to a version conflict with `@types/node`. This was resolved by pinning `@types/node` to version `22.17.2` in the root `package.json`'s `devDependencies` and `pnpm.overrides`. This change was necessary to get the project's `check` and `test` scripts to pass.
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds Markdown linting across the repo: a GitHub Actions workflow for PRs, a root markdownlint config, a lefthook pre-commit hook, and package.json updates including a lint script, devDependencies, and PNPM overrides. Changes
Sequence Diagram(s)sequenceDiagram
participant Dev as Developer
participant Git as GitHub
participant CI as GitHub Actions
participant Node as Setup Node/pnpm
participant Lint as markdownlint-cli2
Dev->>Git: Open/Update PR (changes in *.md/*.mdx)
Git->>CI: Trigger "Markdown Lint" workflow
CI->>Node: Checkout and setup Node 22 + pnpm
CI->>CI: pnpm install
CI->>Lint: Run markdownlint-cli2 on **/*.md, **/*.mdx
Lint-->>CI: Lint results (pass/fail)
CI-->>Git: Report status on PR
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Possibly related PRs
Suggested reviewers
Poem
✨ Finishing Touches🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
github-actions
bot
added
area:ci
There was a problem hiding this comment.
Pull Request Overview
This PR introduces markdown linting to the project using markdownlint-cli2 to ensure consistent markdown formatting across the codebase. The implementation includes automated linting in both pre-commit hooks and CI workflows.
- Adds
markdownlint-cli2as a dev dependency with configuration to disable certain rules - Implements pre-commit hooks and GitHub Actions workflow for automated markdown linting
- Fixes
@types/nodeversion conflict by pinning to version 22.17.2
Reviewed Changes
Copilot reviewed 4 out of 5 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| package.json | Adds markdownlint-cli2 dependency, lint:md script, and pins @types/node version |
| lefthook.yml | Configures pre-commit hook to run markdown linting on staged .md/.mdx files |
| .markdownlint.jsonc | Configuration file disabling line-length, HTML tags, and first heading rules |
| .github/workflows/markdownlint.yml | GitHub Actions workflow to run markdown linting on pull requests |
Files not reviewed (1)
- pnpm-lock.yaml: Language not supported
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
| @@ -0,0 +1,6 @@ | |||
| { | |||
| "default": true, | |||
| "MD013": false, | |||
There was a problem hiding this comment.
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.
| "MD013": false, | |
| "MD013": false, | |
| // MD033 (no-inline-html) is disabled to allow inline HTML in markdown files as required by our documentation style. |
| { | ||
| "default": true, | ||
| "MD013": false, | ||
| "MD033": false, |
There was a problem hiding this comment.
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.
| "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. |
Deploying hatchgrid-web-app with
|
| Latest commit: |
4c31b6b
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1f19d318.hatchgrid-web-app.pages.dev |
| Branch Preview URL: | https://feat-markdown-linting.hatchgrid-web-app.pages.dev |
Deploying hatchgrid-landing-page with
|
| Latest commit: |
4c31b6b
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://783b2a01.hatchgrid.pages.dev |
| Branch Preview URL: | https://feat-markdown-linting.hatchgrid.pages.dev |
Deploying hatchgrid-docs with
|
| Latest commit: |
4c31b6b
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://d5fdc16b.hatchgrid-4b2.pages.dev |
| Branch Preview URL: | https://feat-markdown-linting.hatchgrid-4b2.pages.dev |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled
- Linear integration is disabled
You can enable these sources in your CodeRabbit configuration.
⛔ Files ignored due to path filters (1)
pnpm-lock.yamlis excluded by!**/pnpm-lock.yaml
📒 Files selected for processing (4)
.github/workflows/markdownlint.yml(1 hunks).markdownlint.jsonc(1 hunks)lefthook.yml(1 hunks)package.json(2 hunks)
🧰 Additional context used
🧠 Learnings (1)
📚 Learning: 2025-08-11T20:49:06.813Z
Learnt from: CR
PR: dallay/hatchgrid#0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-08-11T20:49:06.813Z
Learning: Frontend must pass pnpm -r run lint, test, and build
Applied to files:
package.json
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)
- GitHub Check: Validate PR title
- GitHub Check: qodana
- GitHub Check: Analyze (JVM + JS/TS) (java-kotlin)
- GitHub Check: Cloudflare Pages: hatchgrid-docs
🔇 Additional comments (2)
package.json (1)
80-85: Remove redundant@types/nodedevDependencyWe didn’t find a root
tsconfig.json(and the only workspace config underdocs/tsconfig.jsonhas no"types"set), so the project isn’t directly consuming Node types at the root. The PNPM override already pins all transitive@types/nodeto 22.17.2. You can simplify by removing the direct devDependency:
- File:
package.json(around lines 80–85): delete the"@types/node": "22.17.2"entry underdevDependencies, keeping only the override..github/workflows/markdownlint.yml (1)
3-7: Trigger scope: verify whether you want linting on all PRs or only PRs that touch Markdown.The PR objective says “run the linter on all pull requests.” This workflow currently runs only when .md or .mdx files change.
If you want it on all PRs, apply:
on: - pull_request: - paths: - - "**/*.md" - - "**/*.mdx" + pull_request:Otherwise, keep as-is to save CI minutes.
| - run: pnpm install | ||
| - run: npx markdownlint-cli2 "**/*.md" "**/*.mdx" |
There was a problem hiding this comment.
💡 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:mdor
- - 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:mdThe 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.
| - 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.
| { | ||
| "default": true, | ||
| "MD013": false, | ||
| "MD033": false, | ||
| "MD041": false | ||
| } |
There was a problem hiding this comment.
💡 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.jsoncLength 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": falseif 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.
| { | |
| "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.
| # @ref https://evilmartians.github.io/lefthook/ | ||
|
|
||
| pre-commit: | ||
| parallel: true |
There was a problem hiding this comment.
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.
| 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.
| markdownlint: | ||
| glob: "**/*.{md,mdx}" | ||
| run: npx markdownlint-cli2 {staged_files} |
There was a problem hiding this comment.
💡 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.
| "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\"", |
There was a problem hiding this comment.
🧹 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.
Qodana for JVMIt seems all right 👌 No new problems were found according to the checks applied 💡 Qodana analysis was run in the pull request mode: only the changed files were checked Contact Qodana teamContact us at [email protected]
|
This commit introduces markdown linting to the project using
markdownlint-cli2.It includes the following:
markdownlint-cli2..markdownlint.jsoncconfiguration file in the root, which disables theline-lengthandno-bare-urlsrules and sets the emphasis style toasterisk.lint:mdscript in the rootpackage.jsonfor manual linting.lefthookpre-commit hook that runs the linter on staged.mdand.mdxfiles..github/workflows/markdownlint.ymlthat runs the linter on all pull requests.Additionally, this commit includes a fix for the project's dependencies. The build was failing due to a version conflict with
@types/node. This was resolved by pinning@types/nodeto version22.17.2in the rootpackage.json'sdevDependenciesandpnpm.overrides. This change was necessary to get the project'scheckandtestscripts to pass.Screenshots / Evidence
If there are visual changes, add screenshots. For APIs, include request/response examples if applicable.
Breaking changes or migrations?
Merge checklist