Add markdownlint check and fix workflows #274
Merged
+497
−68
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces markdownlint checking and fixing workflows to enforce consistent Markdown formatting across the repository's documentation.
Changes:
- Adds
.markdownlint.jsoncconfiguration file defining linting rules based on project documentation standards - Adds
markdown-check.yamlworkflow to validate Markdown formatting on PRs - Adds
markdown-fix.yamlworkflow to automatically fix formatting issues via bot command or manual trigger - Applies formatting fixes to existing Markdown files (README.md, INSTALLATION.md, DEVELOPING.md, form/README.md, scripts/README.md, CLANG_TIDY_CONFIGURATION.md, CodeQL-README.md, copilot-instructions.md, REUSABLE_WORKFLOWS.md)
- Updates documentation to describe the new markdown workflows
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
.markdownlint.jsonc |
Configuration file defining markdown linting rules matching project standards |
.github/workflows/markdown-check.yaml |
CI workflow to check markdown formatting on PRs |
.github/workflows/markdown-fix.yaml |
Bot-triggered workflow to automatically fix markdown formatting |
.github/REUSABLE_WORKFLOWS.md |
Documentation updated to include markdown workflows |
.github/copilot-instructions.md |
Fixed heading formatting to comply with MD036 rule |
.github/CodeQL-README.md |
Fixed markdown formatting issues (removed incorrect fencing, added blank lines, converted bare URLs to links) |
CLANG_TIDY_CONFIGURATION.md |
Updated format command description to include Markdown |
README.md |
Removed extra blank line (MD012) |
DEVELOPING.md |
Removed extra blank line (MD012) |
INSTALLATION.md |
Fixed heading levels, added blank lines around code blocks, removed trailing blank line |
form/README.md |
Fixed heading levels and formatting, specified code block language |
scripts/README.md |
Fixed table alignment syntax |
greenc-FNAL
changed the title
greenc-FNAL
force-pushed
the
maintenance/markdown-workflows
branch
5 times, most recently
from
83fc259 to
8edfc32
Compare
greenc-FNAL
changed the title
This change introduces a new pair of workflows for checking and fixing the formatting of Markdown files (`.md`). A new `.markdownlint.jsonc` configuration file has been added to define the linting rules, based on the project's documentation standards. The `markdown-check.yaml` workflow runs on pull requests and manual dispatches, using `markdownlint-cli2` to validate formatting. The `markdown-fix.yaml` workflow can be triggered manually or by commenting on a PR with `@phlexbot format` or `@phlexbot markdown-fix`. It uses `markdownlint-cli2 --fix` to fix the files and commits the changes. Co-authored-by: greenc-FNAL <[email protected]> Update workflow docs for `markdown` workflows
- Fix .markdownlint.jsonc by removing redundant "config" wrapper - Clean up .github/CodeQL-README.md by removing redundant code block wrapper - Resolve multiple top-level heading and increment errors in INSTALLATION.md and form/README.md - Make headings unique in .github/REUSABLE_WORKFLOWS.md to resolve MD024 - Fix table column styling in scripts/README.md to resolve MD060 - Address various formatting issues (blank lines, bare URLs, trailing spaces) repository-wide using markdownlint-cli2 --fix Co-authored-by: greenc-FNAL <[email protected]>
- Add 'md' file type support to detect-relevant-changes action - Enable workflow_call support in markdown-fix.yaml - Pin markdownlint actions to specific SHAs with full version annotations - Ensure all action checkouts use full version numbers in annotations (e.g., v6.0.2) - Unified bot command parsing in markdown-fix.yaml to support @<repo>bot format Co-authored-by: greenc-FNAL <[email protected]>
- Fix .markdownlint.jsonc configuration structure - Clean up .github/CodeQL-README.md formatting - Resolve repo-wide markdownlint issues (MD001, MD012, MD024, MD060, etc.) - Add 'md' file type detection to detect-relevant-changes action - Enable workflow_call support in markdown-fix.yaml - Pin actions to SHAs with full semantic version annotations (e.g., # v1.1.0) - Support @<repo>bot format command in markdown-fix.yaml Co-authored-by: greenc-FNAL <[email protected]>
- Configure MD024 to allow duplicate headings among siblings in .markdownlint.jsonc. - Replace pseudo-heading in DEVELOPING.md with a GFM alert block (MD036). Co-authored-by: greenc-FNAL <[email protected]>
greenc-FNAL
force-pushed
the
maintenance/markdown-workflows
branch
from
8edfc32 to
9fda1fa
Compare
This commit updates `markdown-check.yaml` and `markdown-fix.yaml` to align with the repository's established standards for "check/fix" workflow pairs. Changes include: - Added `workflow_call` support to `markdown-check.yaml` with standard inputs. - Implemented the `local_checkout_path` environment variable pattern. - Standardized job naming (e.g., `pre-check`, `detect-changes`). - Added a `markdown-check-skipped` job to `markdown-check.yaml`. - Updated bot command parsing in `markdown-fix.yaml` to use dynamic bot naming and support both generic and specific fix commands. - Improved error messages in `markdown-check.yaml` with helpful bot command instructions. - Fixed logic in `markdown-check.yaml` to correctly handle `workflow_call` and ensure robust result evaluation. Co-authored-by: greenc-FNAL <[email protected]>
- Updated `markdown-check.yaml` and `markdown-fix.yaml` for consistency with other repository workflows (e.g., `cmake-format-check`). - Added robust `workflow_call` support with standard inputs. - Implemented trigger type emulation in `markdown-check.yaml` to intelligently handle relevance checks for automatic vs. manual callers. - Standardized job naming, checkout paths, and dynamic bot command logic. - Updated `REUSABLE_WORKFLOWS.md` with comprehensive documentation for markdown check/fix workflows and fixed pre-existing linting issues. Co-authored-by: greenc-FNAL <[email protected]>
- Standardized `REUSABLE_WORKFLOWS.md` with consistent structure, full usage examples, and comprehensive input documentation for all workflows. - Added documentation for missing workflows to `REUSABLE_WORKFLOWS.md`. - Ensured consistency in job outputs (`has_changes`) across modernized workflows. Co-authored-by: greenc-FNAL <[email protected]>
knoepfel
approved these changes
Feb 2, 2026
Member
knoepfel
left a comment
knoepfel
left a comment
There was a problem hiding this comment.
A nice PR, @greenc-FNAL. Looks great!
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This change introduces a new pair of workflows for checking and fixing the formatting of Markdown files (
.md).A new
.markdownlint.jsoncconfiguration file has been added to define the linting rules, based on the project's documentation standards.The
markdown-check.yamlworkflow runs on pull requests and manual dispatches, usingmarkdownlint-cli2to validate formatting.The
markdown-fix.yamlworkflow can be triggered manually or by commenting on a PR with@phlexbot formator@phlexbot markdown-fix. It usesmarkdownlint-cli2 --fixto fix the files and commits the changes.Co-authored-by: greenc-FNAL [email protected]
Update workflow docs for
markdownworkflows