feat: Set up markdownlint GitHub Action for automated linting (Closes #14) #42
Conversation
|
This is great--really appreciate the demo commit screenshots! Could we have the workflow set up with the |
@egrace479, I've set up the fix logic and tested it. It successfully identifies errors, fixes them, and pushes a commit back to the branch. However, there is what I think is a GitHub Actions limitation, that when the default GITHUB_TOKEN pushes the auto-fix commit, GitHub prevents it from triggering a new CI workflow run (to prevent infinite loops). This creates an issue where someone pushes an MD file with errors. The bot fixes the files and pushes a new commit. The latest commit (the bot's) has no CI run associated with it. If there were unfixable errors remaining (like duplicate headers), the user wouldn't see a "Red X" on the PR. They would have to know to click into the previous commit's logs to see what is wrong. Now there might be a way to make this work using a PAT with repo permissions and adding it as a Secret (BOT_TOKEN). Then updating the workflow to use that token. I think this would allow the bot's commit to trigger a new run and report status correctly but not sure if that's the route we want to take for this. Alternatively, we remove the auto-fix/push logic. Users will have to fix formatting manually, but they will get immediate, reliable Red/Green feedback on every push. Let me know what you think of these options, along with if you have any other solutions in mind or see any other reason causing this. |
@EmersonFras, thanks for the detailed explanation with proposed solutions. We should just remove the auto-fix to make it more robust. We can add a brief explanation in |
egrace479
left a comment
egrace479
left a comment
There was a problem hiding this comment.
A couple notes and a question.
CONTRIBUTING.md
Outdated
| 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" |
There was a problem hiding this comment.
What's the motivation for switching to markdownlint-cli2 compared to the current markdownlint?
There was a problem hiding this comment.
Originally for consistency, since we are using markdownlint-cli2 action in the workflow I made an assumption that using it for local testing would be best practice. It also is a little more robust not needing you to specify the config file. After looking at it though the one major drawback was it doesn't auto filter out non-markdown files when you pass a directory as an argument. Meaning you had to pass something like **/**.md as an argument and then would end up ignoring the .markdownlintignore. Hence it's just easier for me to revert this back to the original markdownlint.
There was a problem hiding this comment.
Great, thanks for clarifying and providing the reasoning to revert too.
Summary
Establishes automated markdown linting using GitHub Actions. As noted in the issue, this ensures consistent formatting across the repository without requiring manual nitpicks during code review.
Changes Implemented
.github/workflows/lint.yaml: A workflow that runsmarkdownlint-cli2on pull requests.CONTRIBUTING.md: Documentation for the new linting automation.Testing
To verify the automation, I pushed a commit containing intentional formatting errors (cda3921).
1. Verification of Failure
The workflow correctly detected the changes and failed the build as expected:
2. Error Reporting
The logs accurately highlighted the specific rule violations (e.g., indentation, invalid headers) within the test file:
Closes #14