docs: clear the markdownlint backlog and gate structure tree-wide#265
Merged
Conversation
Apply mechanical markdown formatting fixes using markdownlint-cli2 --fix: - 60 markdown files auto-fixed for structure and whitespace issues - Renamed docs/facts/resource-types.md → resource-types.yaml (unfenced YAML) and updated inbound link in type-followability.md:365 - Updated stale file counts in .docs-lint-scope header comment This leaves 251 non-auto-fixable findings (mostly line-length and missing fence language tags) that require manual editing. task lint-docs passes with 0 errors. Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
All 27 MD013 errors fixed by rewrapping lines to stay under 120 characters.
…quote Fix MD040 errors (missing fence language) and MD028 (blank line in blockquote).
Fix MD028 (blank lines in blockquotes) in 11 files. Fix MD040 (missing fence language) in 2 files.
Remove trailing whitespace from 10 files (fixes MD009 errors).
Fix all 4 MD040 errors (missing fence language) by adding appropriate language tags.
Add yaml language tag to unfenced code blocks in test fixture README files. Fixes 19 MD040 errors.
Add text language tags to remaining unfenced code blocks. Fixes 8 of 14 remaining MD040 errors.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The earlier batch MD040 fix tagged closing fences as well as opening ones, which silently swallowed the following prose into a code block (and hid four MD029 findings in E2E_DEBUGGING.md behind it). Also converts emphasis-as-heading to real headings and fixes a heading-increment skip. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Emphasis-as-heading, a pipe inside inline code splitting a table cell, a split blockquote and its unspaced list, and duplicate sibling "Migration" headings demoted under their numbered parents. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reflows prose and list lines at the 100-column convention, keeping inline code spans and links atomic so nothing splits mid-token. Three queries that cannot be wrapped move into fenced blocks, one over-long path becomes a reference link, and the F3 heading is shortened rather than wrapped. markdownlint is now clean over all 175 tracked files. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
markdownlint's backlog is cleared, so lint-markdown now runs on every tracked file and a new document cannot regress structure. Vale still has errors in 145 of 167 files, almost all em dashes, so lint-prose stays on the .docs-lint-scope list. DOCS_SCOPE overrides either. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Important Review skippedToo many files! This PR contains 107 files, which is 7 over the limit of 100. To get a review, narrow the scope: Upgrade to a paid plan to raise the limit. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (107)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ 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 |
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Clears the markdownlint backlog across the tree and turns structure into a real
gate:
lint-markdownnow runs on every tracked file, so a new document cannotregress it. 111 findings → 0 over all 175 linted files.
The gate is split, not widened
DOCS_SCOPEstays the single override knob, but the two linters now defaultdifferently because their backlogs are two orders of magnitude apart:
lint-doc-links(doccheck)lint-markdownlint-prose(Vale).docs-lint-scopeGating Vale tree-wide would fail
task linton ~1,100 errors, anddocs/style-guide.mdsays that cleanup must not land as one sweeping commit. Soprose keeps the staged list and it grows as files are cleaned. The stale
"102 of 174 / 148 of 174" figures in
.docs-lint-scope,CONTRIBUTING.md,docs/design/docs-linting.md,AGENTS.md, and the Taskfile comments arere-measured against the current tree.
A defect fixed along the way
An earlier
MD040pass on this branch tagged 36 closing fences as well asopening ones (
```bash … ```yaml). Each one turned the prose that followedinto a code block; in
test/e2e/E2E_DEBUGGING.mdthat hid fourMD029findingsbehind a phantom block. All 36, across 23 files, are back to bare
```.What a reviewer should actually look at
The diff is 107 files, but most of it is mechanical:
inline code spans kept atomic, so nothing split mid-token. Verified by diffing
every touched file with whitespace collapsed: no word changed.
F3heading indocs/future/flux-maintainer-review-status-and-config-model.md, shortenedrather than wrapped (wrapping a heading breaks it); and three unwrappable
PromQL/
if:expressions moved into fenced blocks.Validation
task lint,task test(77.7%, baseline 77.8%, within tolerance), andtask test-e2e(69 passed, 0 failed, 22 skipped) all pass locally.🤖 Generated with Claude Code