chore: fix markdownlint structural issues in docs (MD022/MD032/MD031)#196
chore: fix markdownlint structural issues in docs (MD022/MD032/MD031)#196Prekzursil wants to merge 1 commit into
Conversation
Adds blank lines around headings, lists, and fenced code blocks and removes stray trailing whitespace across 11 documentation files via markdownlint-cli2 --fix, clearing the auto-fixable subset of the Codacy markdownlint backlog. Formatter-only: no rendered-content change (MD011/MD014 untouched; MD013 line-length and MD040 language hints left for follow-up, NOT suppressed). README.md and TODO.md are deferred to a separate line-ending-normalization PR (mixed CRLF/LF committed endings would add noise here).
|
Unable to trigger custom agent "Code Reviewer". You have run out of credits 😔 |
Qodo reviews are paused for this user.Troubleshooting steps vary by plan Learn more → On a Teams plan? Using GitHub Enterprise Server, GitLab Self-Managed, or Bitbucket Data Center? |
|
CodeAnt AI is reviewing your PR. Thanks for using CodeAnt! 🎉We're free for open-source projects. if you're enjoying it, help us grow by sharing. Share on X · |
📝 WalkthroughWalkthroughThis PR restructures and reformats documentation across the repository to improve Markdown readability and organizational consistency. AGENTS.md introduces section headings for governance workflows. Core documentation files including governance, branch protection, KPI metrics, validation, and Baseline-Lite package guides receive whitespace and layout improvements without changing substantive content. ChangesDocumentation Formatting and Structure Improvements
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 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 |
codeant-ai
Bot
added
the
size:L
Up to standards ✅🟢 Issues
|
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
| Exact filenames differ by platform and bundler; use the files generated in `apps/desktop/src-tauri/target/release/bundle/`. | ||
|
|
||
| 3) Create and upload `latest.json` as a release asset with this shape: | ||
| 1) Create and upload `latest.json` as a release asset with this shape: |
There was a problem hiding this comment.
Bug: The auto-formatter incorrectly renumbered the manual release steps in UPDATER.md, causing the critical third step to be mislabeled and breaking the release instructions.
Severity: HIGH
Suggested Fix
Disable the auto-formatter rule for this list or manually correct the numbering to restore the 1), 2), 3) sequence. You can add <!-- markdownlint-disable-next-line MD029 --> before the list to disable the rule for that section.
Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.
Location: apps/desktop/UPDATER.md#L72
Potential issue: In the `UPDATER.md` file, the auto-formatter has incorrectly renumbered
a list in the manual release instructions. The sequence of steps is now `1), 2), 1)`
instead of the correct `1), 2), 3)`. This mislabeling breaks the logical flow of the
procedure. The third step, which involves creating and uploading `latest.json`, is
critical for the Tauri updater to function. A user following these broken instructions
would miss this step, causing application updates to fail silently for end-users.
Did we get this right? 👍 / 👎 to inform future reviews.
| - [ ] Adjust thresholds and targets based on baseline | ||
|
|
||
| ### Phase 6: Team Onboarding (Week 3-4) | ||
|
|
||
| - [ ] Document rollout in project README | ||
| - [ ] Add CONTRIBUTING.md with local setup | ||
| - [ ] Create onboarding issue template |
There was a problem hiding this comment.
Bug: The auto-formatter replaced required tabs with spaces in a makefile code block, which will cause make to fail when a user copies the code.
Severity: MEDIUM
Suggested Fix
Re-introduce the tab characters at the beginning of the recipe lines in the makefile code block. To prevent the auto-formatter from removing them again, consider using a directive like <!-- markdownlint-disable-next-line MD010 -->.
Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.
Location: docs/BASELINE_LITE_PACKAGE.md#L271-L277
Potential issue: In the `BASELINE_LITE_PACKAGE.md` documentation, an auto-formatter has
replaced the required tab characters in a `makefile` code block with spaces. GNU Make
requires that recipe lines (the commands under a target) must be indented with a literal
tab character, not spaces. As a result, anyone copying this code snippet and trying to
use it with `make` will encounter a `*** missing separator. Stop.` error, preventing the
makefile from executing.
Did we get this right? 👍 / 👎 to inform future reviews.
![codeant-ai[bot]](https://avatars.githubusercontent.com/in/646884?s=60&v=4){kind=small}
| ```makefile | ||
| frontend-test: | ||
| cd apps/web && npm test | ||
| cd apps/web && npm test | ||
|
|
||
| backend-test: | ||
| PYTHONPATH=.:apps/api python -m pytest apps/api/tests | ||
| PYTHONPATH=.:apps/api python -m pytest apps/api/tests | ||
|
|
There was a problem hiding this comment.
🟠 Architect Review — HIGH
The PR assumes hard-tab cleanup is formatter-only, but in this Makefile example the recipe command lines were changed from tab-indented to space-indented, which makes the snippet invalid when copied into a real Makefile (missing separator).
Suggestion: Keep literal tab indentation for recipe lines inside ```makefile fences (or explicitly document \t), and exclude these blocks from hard-tab autofix so documentation examples remain executable as written.
Fix in Cursor | Fix in VSCode Claude
(Use Cmd/Ctrl + Click for best experience)
Prompt for AI Agent 🤖
This is an **Architect / Logical Review** comment left during a code review. These reviews are first-class, important findings — not optional suggestions. Do NOT dismiss this as a 'big architectural change' just because the title says architect review; most of these can be resolved with a small, localized fix once the intent is understood.
**Path:** docs/BASELINE_LITE_PACKAGE.md
**Line:** 317:323
**Comment:**
*HIGH: The PR assumes hard-tab cleanup is formatter-only, but in this Makefile example the recipe command lines were changed from tab-indented to space-indented, which makes the snippet invalid when copied into a real Makefile (`missing separator`).
Validate the correctness of the flagged issue. If correct, How can I resolve this? If you propose a fix, implement it and please make it concise.
If a suggested approach is provided above, use it as the authoritative instruction. If no explicit code suggestion is given, you MUST still draft and apply your own minimal, localized fix — do not punt back with 'no suggestion provided, review manually'. Keep the change as small as possible: add a guard clause, gate on a loading state, reorder an await, wrap in a conditional, etc. Do not refactor surrounding code or expand scope beyond the finding.
Once fix is implemented, also check other comments on the same PR, and ask user if the user wants to fix the rest of the comments as well. if said yes, then fetch all the comments validate the correctness and implement a minimal fix
|
CodeAnt AI finished reviewing your PR. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@apps/desktop/UPDATER.md`:
- Line 72: The numbered steps in the UPDATER.md manual release sequence reset
from "2)" back to "1)" at the line that currently reads "1) Create and upload
`latest.json`...", break the sequence; update that marker to "3)" so the list
continues deterministically (locate the step text "Create and upload
`latest.json` as a release asset with this shape:" and change its leading "1)"
to "3)").
🪄 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: defaults
Review profile: CHILL
Plan: Pro
Run ID: 86f26af6-769b-40fc-8ef9-ca961c9cbdb4
📒 Files selected for processing (11)
AGENTS.mdapps/desktop/README.mdapps/desktop/UPDATER.mddocs/BASELINE_LITE_PACKAGE.mddocs/BASELINE_LITE_QUICKSTART.mddocs/BRANCH_PROTECTION.mddocs/GOVERNANCE.mddocs/KPI_METRICS.mddocs/PHASE_3_4_VALIDATION.mddocs/regressions/README.mdservices/worker/README.md
| Exact filenames differ by platform and bundler; use the files generated in `apps/desktop/src-tauri/target/release/bundle/`. | ||
|
|
||
| 3) Create and upload `latest.json` as a release asset with this shape: | ||
| 1) Create and upload `latest.json` as a release asset with this shape: |
There was a problem hiding this comment.
Fix manual release step numbering continuity.
Line 72 restarts at 1) after step 2), which can break sequence clarity in some renderers. Continue numbering as step 3) for deterministic procedural order.
Suggested fix
-1) Create and upload `latest.json` as a release asset with this shape:
+3) Create and upload `latest.json` as a release asset with this shape:📝 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.
| 1) Create and upload `latest.json` as a release asset with this shape: | |
| 3) Create and upload `latest.json` as a release asset with this shape: |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@apps/desktop/UPDATER.md` at line 72, The numbered steps in the UPDATER.md
manual release sequence reset from "2)" back to "1)" at the line that currently
reads "1) Create and upload `latest.json`...", break the sequence; update that
marker to "3)" so the list continues deterministically (locate the step text
"Create and upload `latest.json` as a release asset with this shape:" and change
its leading "1)" to "3)").
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 11 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="docs/BASELINE_LITE_PACKAGE.md">
<violation number="1" location="docs/BASELINE_LITE_PACKAGE.md:319">
P2: MD010 auto-fix replaced tabs with spaces inside a `makefile` fenced code block. Makefile recipes require tab indentation — space-indented recipes produce a missing-separator error. This makes the documentation inaccurate for anyone copying the example.</violation>
</file>
<file name="apps/desktop/UPDATER.md">
<violation number="1" location="apps/desktop/UPDATER.md:72">
P2: The auto-formatter incorrectly renumbered this step from `3)` to `1)`, breaking the procedural sequence. The manual release steps should read `1)`, `2)`, `3)` — this third step (creating and uploading `latest.json`) is critical for the Tauri updater to function and its mislabeling harms clarity.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| ```makefile | ||
| frontend-test: | ||
| cd apps/web && npm test | ||
| cd apps/web && npm test |
There was a problem hiding this comment.
P2: MD010 auto-fix replaced tabs with spaces inside a makefile fenced code block. Makefile recipes require tab indentation — space-indented recipes produce a missing-separator error. This makes the documentation inaccurate for anyone copying the example.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At docs/BASELINE_LITE_PACKAGE.md, line 319:
<comment>MD010 auto-fix replaced tabs with spaces inside a `makefile` fenced code block. Makefile recipes require tab indentation — space-indented recipes produce a missing-separator error. This makes the documentation inaccurate for anyone copying the example.</comment>
<file context>
@@ -265,12 +313,13 @@ on:
```makefile
frontend-test:
- cd apps/web && npm test
+ cd apps/web && npm test
backend-test:
</file context>
| cd apps/web && npm test | |
| cd apps/web && npm test |
| Exact filenames differ by platform and bundler; use the files generated in `apps/desktop/src-tauri/target/release/bundle/`. | ||
|
|
||
| 3) Create and upload `latest.json` as a release asset with this shape: | ||
| 1) Create and upload `latest.json` as a release asset with this shape: |
There was a problem hiding this comment.
P2: The auto-formatter incorrectly renumbered this step from 3) to 1), breaking the procedural sequence. The manual release steps should read 1), 2), 3) — this third step (creating and uploading latest.json) is critical for the Tauri updater to function and its mislabeling harms clarity.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At apps/desktop/UPDATER.md, line 72:
<comment>The auto-formatter incorrectly renumbered this step from `3)` to `1)`, breaking the procedural sequence. The manual release steps should read `1)`, `2)`, `3)` — this third step (creating and uploading `latest.json`) is critical for the Tauri updater to function and its mislabeling harms clarity.</comment>
<file context>
@@ -69,7 +69,7 @@ Manual (if needed):
Exact filenames differ by platform and bundler; use the files generated in `apps/desktop/src-tauri/target/release/bundle/`.
-3) Create and upload `latest.json` as a release asset with this shape:
+1) Create and upload `latest.json` as a release asset with this shape:
```json
</file context>
| 1) Create and upload `latest.json` as a release asset with this shape: | |
| 3) Create and upload `latest.json` as a release asset with this shape: |
1 participant
User description
What
Runs
markdownlint-cli2 --fixover the documentation set and commits the auto-fixable, formatter-only subset across 11 files (213 insertions / 6 deletions): blank lines around headings (MD022), lists (MD032) and fenced code blocks (MD031), plus a few stray trailing-space (MD009) / hard-tab (MD010) fixes.Why
Clears the auto-fixable part of the dominant Codacy markdownlint backlog (a 100-issue census sample was 100% Markdown/CodeStyle in docs). This is Layer-2 step (a) of the green-main autofix plan (
docs/quality-zero/GREEN-MAIN-AUTOFIX-FLEET-SOLUTION.md).Safety / honesty
$in code) were not present and are not touched. Verified the diff is blank-line/whitespace only (git diff --ignore-cr-at-eol≡ the structural change).MD013(line-length, ~328) andMD040(code-fence language) are not auto-fixable and are left as open findings for a follow-up — not disabled/ignored.README.mdandTODO.mddeferred to a separate line-ending-normalization PR — they carry mixed CRLF/LF committed endings that would add hundreds of lines of EOL noise here.Note
This repo's
mainhas 19 required checks (many currently red pre-existing) and auto-merge is not enabled, so this PR is for human review/merge — it does not self-merge.Summary by cubic
Auto-fixed markdownlint issues in docs using
markdownlint-cli2 --fixacross 11 files to add required blank lines around headings, lists, and code fences (MD022/MD032/MD031) and clean up trailing spaces/tabs. Formatter-only; no rendered-content changes; MD013/MD040 left for follow-up;README.mdandTODO.mddeferred pending line-ending normalization.Written for commit 56c99d6. Summary will update on new commits.
CodeAnt-AI Description
Fix markdown spacing and list formatting across documentation
What Changed
Impact
✅ Cleaner docs pages✅ Fewer markdownlint warnings✅ Easier-to-read setup and policy guides💡 Usage Guide
Checking Your Pull Request
Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.
Talking to CodeAnt AI
Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:
This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.
Example
Preserve Org Learnings with CodeAnt
You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:
This helps CodeAnt AI learn and adapt to your team's coding style and standards.
Example
Retrigger review
Ask CodeAnt AI to review the PR again, by typing:
Check Your Repository Health
To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.
Summary by CodeRabbit