chore(markdown): add markdownlint CI job and fix lint violations#1753
Conversation
ada1f1b to
671e512
Compare
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds markdownlint configuration and CI integration (Taskfile, .env, GitHub Actions job) and applies widespread Markdown formatting fixes: code-fence languages, list indentation, trailing newlines, and URL formatting across many docs. No code-level exports changed. Changes
Sequence Diagram(s)sequenceDiagram
participant GH as GitHub Actions
participant Repo as Repository
participant Runner as Actions Runner (node setup)
participant npx as npx/markdownlint-cli2
GH->>Repo: workflow triggered (markdown.yml)
GH->>Runner: start job "lint"
Runner->>Repo: source .env (read MARKDOWNLINT_CLI2_VERSION)
Runner->>Runner: setup Node.js
Runner->>npx: run npx markdownlint-cli2@${MARKDOWNLINT_CLI2_VERSION} --config .github/config/.markdownlint-cli2.yaml "**/*.md"
npx->>Repo: read config & ignores, lint markdown files
npx-->>Runner: exit code / report
Runner-->>GH: job success/failure
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
️✅ There are no secrets present in this pull request anymore.If these secrets were true positive and are still valid, we highly recommend you to revoke them. 🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request. |
|
Addressed review feedback:
|
671e512 to
909861b
Compare
|
Rebased on main and updated the linter approach:
|
909861b to
39b9029
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (3)
cli/docs/reference/.markdownlint-cli2.yaml (1)
12-12: Consider adding a comment explaining MD032 disable.For consistency with other rule disables in this file, consider adding a comment explaining why MD032 (lists should be surrounded by blank lines) is disabled for CLI-generated documentation.
📝 Suggested addition
MD046: false # cobra uses both fenced and indented code block styles in different sections - MD032: false + MD032: false # cobra generates lists without surrounding blank lines in some contexts🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@cli/docs/reference/.markdownlint-cli2.yaml` at line 12, Add a brief inline comment next to the MD032: false entry explaining why the "lists should be surrounded by blank lines" rule is disabled for this section (e.g., because CLI-generated docs intentionally omit surrounding blank lines), by updating the configuration entry for MD032: false so the comment is adjacent to that exact key to match the style of other rule disables in the file..github/workflows/markdown.yml (1)
34-40: Consider aligning the command structure with the local Taskfile.The CI command uses a different argument order than the local
task markdownlintcommand intools.Taskfile.yml:
- CI:
npx markdownlint-cli2 "**/*.md" --config ...- Local:
npx markdownlint-cli2 --config ... '{{ .ROOT_DIR }}/**/*.md'While markdownlint-cli2 should handle both orderings, aligning them would ensure developers get identical results locally and in CI, reducing potential debugging friction.
♻️ Suggested alignment with local Taskfile
- name: Run linter - run: npx markdownlint-cli2 "**/*.md" --config .github/config/.markdownlint-cli2.yaml + run: npx markdownlint-cli2 --config .github/config/.markdownlint-cli2.yaml "**/*.md"🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/workflows/markdown.yml around lines 34 - 40, Update the "Run linter" step in the GitHub workflow so the markdownlint-cli2 invocation matches the local Taskfile invocation used by the task named "markdownlint" in tools.Taskfile.yml: move the --config argument before the file glob and use the same root-aware glob (the Taskfile's '{{ .ROOT_DIR }}/**/*.md' pattern or an equivalent explicit repo-root path) so CI runs the same command order and target files as local `task markdownlint`.tools.Taskfile.yml (1)
108-114: Consider aligning CI workflow to use this task.The task is well-structured, but the CI workflow (
.github/workflows/markdown.ymllines 34-40) runsnpx markdownlint-cli2directly instead of invokingtask tools:markdownlint. This creates potential for configuration drift between local and CI environments.Consider updating the CI workflow to use:
run: task tools:markdownlintThis would ensure consistent behavior between local development and CI, and centralize the markdownlint configuration in one place.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@tools.Taskfile.yml` around lines 108 - 114, The CI is invoking markdownlint directly which can diverge from the Taskfile task; update the workflow step that currently runs the direct npx command to instead execute the Taskfile task by replacing that run command with "task tools:markdownlint" so the CI uses the same 'markdownlint' task definition and variables as local/dev environments.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@tools.Taskfile.yml`:
- Line 6: The MARKDOWNLINT_CLI2_TARGET_VERSION variable is undefined and unused;
either add MARKDOWNLINT_CLI2_VERSION to the .env and pin markdownlint installs
to MARKDOWNLINT_CLI2_TARGET_VERSION (update the markdownlint task to install/use
the target version via the same pattern as GOLANGCI_LINT_TARGET_VERSION and
DEEPCOPY_GEN_TARGET_VERSION) or remove the MARKDOWNLINT_CLI2_TARGET_VERSION
declaration entirely and keep the markdownlint task using npx; update references
in the markdownlint task (the task name "markdownlint" and any npx invocation)
to consistently use the chosen approach.
---
Nitpick comments:
In @.github/workflows/markdown.yml:
- Around line 34-40: Update the "Run linter" step in the GitHub workflow so the
markdownlint-cli2 invocation matches the local Taskfile invocation used by the
task named "markdownlint" in tools.Taskfile.yml: move the --config argument
before the file glob and use the same root-aware glob (the Taskfile's '{{
.ROOT_DIR }}/**/*.md' pattern or an equivalent explicit repo-root path) so CI
runs the same command order and target files as local `task markdownlint`.
In `@cli/docs/reference/.markdownlint-cli2.yaml`:
- Line 12: Add a brief inline comment next to the MD032: false entry explaining
why the "lists should be surrounded by blank lines" rule is disabled for this
section (e.g., because CLI-generated docs intentionally omit surrounding blank
lines), by updating the configuration entry for MD032: false so the comment is
adjacent to that exact key to match the style of other rule disables in the
file.
In `@tools.Taskfile.yml`:
- Around line 108-114: The CI is invoking markdownlint directly which can
diverge from the Taskfile task; update the workflow step that currently runs the
direct npx command to instead execute the Taskfile task by replacing that run
command with "task tools:markdownlint" so the CI uses the same 'markdownlint'
task definition and variables as local/dev environments.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 40b5f80d-3c9c-4284-ab7e-8c99ffa71f60
📒 Files selected for processing (19)
.github/config/.markdownlint-cli2.yaml.github/workflows/markdown.ymlCONTRIBUTING.mdRELEASE_PROCESS.mdcli/docs/reference/.markdownlint-cli2.yamlconformance/README.mdconformance/scenarios/sovereign/README.mddocs/adr/0012_construct_as_transformation.mddocs/adr/0013_sovereign_cloud_reference_scenario.mddocs/adr/0014_conformance_test_suite.mddocs/community/README.mddocs/steering/GOVERNANCE.mddocs/steering/meeting-notes/2025-11-03.mddocs/steering/meeting-notes/2025-12-01.mddocs/steering/meeting-notes/2026-01-05.mddocs/steering/meeting-notes/2026-02-02.mddocs/steering/meeting-notes/2026-03-02.mddocs/steering/meeting-notes/2026-04-06.mdtools.Taskfile.yml
33ad07c to
98100da
Compare
Skarlso
left a comment
There was a problem hiding this comment.
I have two comments, other then that this looks okay. 👍
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.env:
- Line 14: The .env file currently lacks a trailing newline which triggers
dotenv-linter's EndingBlankLine; open the .env file and add a single newline
character at the end of the file (after the MARKDOWNLINT_CLI2_VERSION=0.22.0
line) so the file ends with a blank line/EOF newline to satisfy the linter.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: f3ff9207-31c4-46f0-961c-b615f14ba710
📒 Files selected for processing (3)
.env.github/workflows/markdown.ymltools.Taskfile.yml
🚧 Files skipped from review as they are similar to previous changes (1)
- .github/workflows/markdown.yml
|
Thanks. I will "fix" the spell checker in my followup for the website. :) |
|
Caution Review failedAn error occurred during the review process. Please try again later. 📝 WalkthroughWalkthroughThis PR adds Markdown linting infrastructure (config, Taskfile task, and a GitHub Actions job) and applies widespread documentation formatting fixes: code fence types, list indentation, trailing newlines, and URL formatting across many Markdown files. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~15 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
b901b00 to
0adc042
Compare
✅ Deploy Preview for ocm-website ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
♻️ Duplicate comments (1)
.env (1)
14-14:⚠️ Potential issue | 🟡 MinorAdd trailing newline at EOF.
This still trips
dotenv-linter(EndingBlankLine) and creates avoidable CI noise.Suggested fix
MARKDOWNLINT_CLI2_VERSION=0.22.0 +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.env at line 14, The .env file is missing a trailing newline which triggers dotenv-linter's EndingBlankLine; open the .env file and add a single newline character at EOF so the last entry (MARKDOWNLINT_CLI2_VERSION=0.22.0) is followed by a blank line, then save the file to remove the linter warning.
🧹 Nitpick comments (1)
docs/steering/meeting-notes/2026-03-02.md (1)
44-44: Optional wording polish: hyphenate “blog-style page”.Tiny readability/grammar cleanup for the phrase.
Suggested tweak
- - [x] Gerald to check for a blog style page for announcements etc. on the website. (Jakob & Gerald to plan) + - [x] Gerald to check for a blog-style page for announcements etc. on the website. (Jakob & Gerald to plan)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/steering/meeting-notes/2026-03-02.md` at line 44, Update the checklist item text to hyphenate “blog-style page”: replace the phrase "a blog style page for announcements etc. on the website." in the meeting note line containing "Gerald to check for a blog style page for announcements etc. on the website. (Jakob & Gerald to plan)" with "a blog-style page for announcements etc. on the website." so it reads with the correct hyphenation.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Duplicate comments:
In @.env:
- Line 14: The .env file is missing a trailing newline which triggers
dotenv-linter's EndingBlankLine; open the .env file and add a single newline
character at EOF so the last entry (MARKDOWNLINT_CLI2_VERSION=0.22.0) is
followed by a blank line, then save the file to remove the linter warning.
---
Nitpick comments:
In `@docs/steering/meeting-notes/2026-03-02.md`:
- Line 44: Update the checklist item text to hyphenate “blog-style page”:
replace the phrase "a blog style page for announcements etc. on the website." in
the meeting note line containing "Gerald to check for a blog style page for
announcements etc. on the website. (Jakob & Gerald to plan)" with "a blog-style
page for announcements etc. on the website." so it reads with the correct
hyphenation.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 102bf597-9045-4018-a92d-1eeba578a1f6
📒 Files selected for processing (21)
.env.github/config/.markdownlint-cli2.yaml.github/workflows/markdown.ymlCONTRIBUTING.mdRELEASE_PROCESS.mdcli/docs/reference/.markdownlint-cli2.yamlconformance/README.mdconformance/scenarios/sovereign/README.mddocs/adr/0012_construct_as_transformation.mddocs/adr/0013_sovereign_cloud_reference_scenario.mddocs/adr/0014_conformance_test_suite.mddocs/community/README.mddocs/steering/GOVERNANCE.mddocs/steering/meeting-notes/2025-11-03.mddocs/steering/meeting-notes/2025-12-01.mddocs/steering/meeting-notes/2026-01-05.mddocs/steering/meeting-notes/2026-02-02.mddocs/steering/meeting-notes/2026-03-02.mddocs/steering/meeting-notes/2026-04-07.mddocs/steering/meeting-notes/2026-05-04.mdtools.Taskfile.yml
✅ Files skipped from review due to trivial changes (14)
- conformance/README.md
- docs/steering/GOVERNANCE.md
- docs/community/README.md
- cli/docs/reference/.markdownlint-cli2.yaml
- conformance/scenarios/sovereign/README.md
- .github/config/.markdownlint-cli2.yaml
- docs/adr/0014_conformance_test_suite.md
- CONTRIBUTING.md
- docs/steering/meeting-notes/2026-01-05.md
- docs/steering/meeting-notes/2026-05-04.md
- docs/steering/meeting-notes/2025-11-03.md
- docs/adr/0013_sovereign_cloud_reference_scenario.md
- docs/steering/meeting-notes/2026-04-07.md
- RELEASE_PROCESS.md
🚧 Files skipped from review as they are similar to previous changes (2)
- tools.Taskfile.yml
- docs/adr/0012_construct_as_transformation.md
- Add lint job to markdown.yml using npx markdownlint-cli2 (respects per-directory configs) - Add markdownlint task to tools.Taskfile.yml using npx markdownlint-cli2 - Ignore auto-generated kubernetes/controller/chart/README.md from linting - Disable MD060 in root markdownlint config - Disable MD032 in cli/docs/reference markdownlint config - Fix all markdownlint violations across the repo (auto-fix + manual) - Fix MD040 in conformance/scenarios/sovereign/README.md and RELEASE_PROCESS.md Signed-off-by: Jakob Möller <contact@jakob-moeller.com>
- Remove unused MARKDOWNLINT_CLI2_TARGET_VERSION variable (MARKDOWNLINT_CLI2_VERSION not in .env) - Add comment explaining why MD032 is disabled in cli/docs/reference config - Align CI workflow argument order with local Taskfile (--config before glob) Signed-off-by: Jakob Möller <jakob.moeller@sap.com>
- Wrap bare URLs in angle brackets (MD034) - Fix list indentation to use 2-space increments (MD007) - Remove extra blank lines (MD012) - Add trailing newline (MD047) Signed-off-by: Jakob Möller <jakob.moeller@sap.com>
- Add MARKDOWNLINT_CLI2_VERSION=0.22.0 to .env (with Renovate annotation) - Add MARKDOWNLINT_CLI2_TARGET_VERSION var to Taskfile referencing .env value - Pin npx invocation to the versioned var in both Taskfile and CI workflow - Read version from .env in CI via `source .env` pattern (consistent with ci.yml) - Add actions/setup-node step before linter run for consistency with other Node jobs Signed-off-by: Jakob Möller <jakob.moeller@sap.com>
website/ has its own config (.github/config/website.markdownlint-cli2.yaml) and dedicated workflow (website-verify-markdown.yml), so it should not be linted by the general markdownlint job. Signed-off-by: Jakob Möller <jakob.moeller@sap.com>
website/ has its own spellcheck config and workflow (website-verify-markdown.yml), so it should not be checked by the general spellcheck job. Signed-off-by: Jakob Möller <jakob.moeller@sap.com>
Add technical terms from website/ content that were flagged as misspelled: auditable, autoscaler, callout, CET, cryptographically, Diataxis, Docker's, dockermulti, filesystems, frontend, frontmatter, Fulcio, hasMermaid, linkTitle, MediaType's, microservice/microservices, Namespaced, nerdctl, ocmv, OpenSSL, prem, renderer, shortcodes, src, subheadline, svg, Terraform, webshop, WSL, Contributability, Misattributed Signed-off-by: Jakob Möller <jakob.moeller@sap.com>
0adc042 to
f0c0288
Compare
…n-component-model#1753) <!-- markdownlint-disable MD041 --> #### What this PR does / why we need it - Add `lint` job to `markdown.yml` workflow using `task tools:markdownlint` - Add `markdownlint` and `markdownlint/install` tasks to `tools.Taskfile.yml` with version management #### Which issue(s) this PR fixes <!-- Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`. --> runs automatic linting and gives a task to fix that linting. --------- Signed-off-by: Jakob Möller <contact@jakob-moeller.com> Signed-off-by: Jakob Möller <jakob.moeller@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
…n-component-model#1753) <!-- markdownlint-disable MD041 --> #### What this PR does / why we need it - Add `lint` job to `markdown.yml` workflow using `task tools:markdownlint` - Add `markdownlint` and `markdownlint/install` tasks to `tools.Taskfile.yml` with version management #### Which issue(s) this PR fixes <!-- Usage: `Fixes #<issue number>`, or `Fixes (paste link of issue)`. --> runs automatic linting and gives a task to fix that linting. --------- Signed-off-by: Jakob Möller <contact@jakob-moeller.com> Signed-off-by: Jakob Möller <jakob.moeller@sap.com> Signed-off-by: Gerald Morrison (SAP) <gerald.morrison@sap.com>
What this PR does / why we need it
lintjob tomarkdown.ymlworkflow usingtask tools:markdownlintmarkdownlintandmarkdownlint/installtasks totools.Taskfile.ymlwith version managementWhich issue(s) this PR fixes
runs automatic linting and gives a task to fix that linting.