Skip to content

Commit 4dfc940

Browse files
Copilotjeduden
Copilot
and
jeduden
authored
docs: merge rules-lacks table into structural linting with plan annotations
Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/bb8f681c-272f-45b5-90e0-70c7aed81522 Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
1 parent 8128f52 commit 4dfc940

1 file changed

Lines changed: 39 additions & 40 deletions

File tree

‎docs/background/markdown-linters.md‎

Lines changed: 39 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -199,48 +199,45 @@ Weaknesses:
199199

200200
### Structural Linting
201201

202-
| Capability | mdsmith | markdownlint | remark-lint |
203-
|---------------------|--------------------------------|------------------------------------------|---------------------------------|
204-
| Heading hierarchy | [MDS003][mds003] | [MD001][md001] | [heading-increment][rl-hi] |
205-
| First-line heading | [MDS004][mds004] | [MD041][md041] | [first-heading-level][rl-fhl] |
206-
| Duplicate headings | [MDS005][mds005] | [MD024][md024] | [no-duplicate-headings][rl-ndh] |
207-
| Blank line spacing | [MDS013][mds013]-[015][mds015] | [MD022][md022],[025][md025],[031][md031] | plugins |
208-
| List indentation | [MDS016][mds016] | [MD007][md007] | [list-item-indent][rl-lii] |
209-
| Code fence style | [MDS010][mds010] | [MD048][md048] | [fenced-code-flag][rl-fcf] |
210-
| Code block language | [MDS011][mds011] | [MD040][md040] | [fenced-code-flag][rl-fcf] |
211-
| Bare URLs | [MDS012][mds012] | [MD034][md034] | [no-literal-urls][rl-nlu] |
212-
| Line length | [MDS001][mds001] | [MD013][md013] | [maximum-line-length][rl-mll] |
213-
| Trailing spaces | [MDS006][mds006] | [MD009][md009] | [hard-break-spaces][rl-hbs] |
202+
| Capability | mdsmith | markdownlint | remark-lint |
203+
|---------------------|--------------------------------|------------------------------------------|---------------------------------------------------|
204+
| Heading hierarchy | [MDS003][mds003] | [MD001][md001] | [heading-increment][rl-hi] |
205+
| First-line heading | [MDS004][mds004] | [MD041][md041] | [first-heading-level][rl-fhl] |
206+
| Duplicate headings | [MDS005][mds005] | [MD024][md024] | [no-duplicate-headings][rl-ndh] |
207+
| Blank line spacing | [MDS013][mds013]-[015][mds015] | [MD022][md022],[025][md025],[031][md031] | plugins |
208+
| List indentation | [MDS016][mds016] | [MD007][md007] | [list-item-indent][rl-lii] |
209+
| Code fence style | [MDS010][mds010] | [MD048][md048] | [fenced-code-flag][rl-fcf] |
210+
| Code block language | [MDS011][mds011] | [MD040][md040] | [fenced-code-flag][rl-fcf] |
211+
| Bare URLs | [MDS012][mds012] | [MD034][md034] | [no-literal-urls][rl-nlu] |
212+
| Line length | [MDS001][mds001] | [MD013][md013] | [maximum-line-length][rl-mll] |
213+
| Trailing spaces | [MDS006][mds006] | [MD009][md009] | [hard-break-spaces][rl-hbs] |
214+
| Inline HTML | planned ([plan 105][plan105]) | [MD033][md033] | [no-html][rl-nh] |
215+
| Image alt text | [MDS032][mds032] | [MD045][md045] | [no-empty-image-alt-text][rl-neiat] (third-party) |
216+
| OL numbering | [MDS046][mds046] | [MD029][md029] | [ordered-list-marker-style][rl-olms] |
217+
| UL marker style | planned ([plan 109][plan109]) | [MD004][md004] | [unordered-list-marker-style][rl-ulms] |
218+
| Emphasis style | planned ([plan 106][plan106]) | [MD049][md049], [MD050][md050] | [emphasis-marker][rl-em] |
219+
| HR style | planned ([plan 108][plan108]) | [MD035][md035] | [rule-style][rl-rs] |
220+
| Ambiguous emphasis | planned ([plan 111][plan111]) | [MD037][md037] | no |
221+
| Space in code | no | [MD038][md038] | no |
222+
| Space in links | no | [MD039][md039] | no |
223+
| Proper names | no | [MD044][md044] | no |
224+
| Required headings | [MDS020][mds020] (via schema) | [MD043][md043] | no |
225+
| Single H1 | no | [MD047][md047] | no |
226+
| Link fragments | [MDS027][mds027] (cross-file) | [MD051][md051] | no |
227+
| Reference links | planned ([plan 107][plan107]) | [MD052][md052], [MD053][md053] | no |
214228

215229
All three cover core structural rules. markdownlint has
216-
the broadest rule set (~60 rules). mdsmith and remark-lint
217-
are comparable in structural coverage.
218-
219-
### Rules mdsmith Lacks
220-
221-
markdownlint has ~30 rules without mdsmith equivalents.
222-
Notable gaps:
223-
224-
| Rule area | markdownlint | remark-lint |
225-
|-------------------|--------------------------------|---------------------------------------------------|
226-
| Inline HTML | [MD033][md033] no-inline-html | [no-html][rl-nh] |
227-
| Image alt text | [MD045][md045] no-alt-text | [no-empty-image-alt-text][rl-neiat] (third-party) |
228-
| OL numbering | [MD029][md029] ol-prefix | [ordered-list-marker-style][rl-olms] |
229-
| UL marker style | [MD004][md004] ul-style | [unordered-list-marker-style][rl-ulms] |
230-
| Emphasis style | [MD049][md049], [MD050][md050] | [emphasis-marker][rl-em] |
231-
| HR style | [MD035][md035] hr-style | [rule-style][rl-rs] |
232-
| Space in emphasis | [MD037][md037] | no |
233-
| Space in code | [MD038][md038] | no |
234-
| Space in links | [MD039][md039] | no |
235-
| Proper names | [MD044][md044] | no |
236-
| Required headings | [MD043][md043] | no |
237-
| Single H1 | [MD047][md047] | no |
238-
| Link fragments | [MD051][md051] | no |
239-
| Reference links | [MD052][md052], [MD053][md053] | no |
240-
241-
mdsmith covers readability, tokens, and generated content
242-
rather than formatting details. Teams that need full
243-
coverage can pair mdsmith with markdownlint.
230+
the broadest rule set. mdsmith has plans for inline
231+
HTML ([plan 105][plan105]), UL marker style
232+
([plan 109][plan109]), emphasis style
233+
([plan 106][plan106]), HR style ([plan 108][plan108]),
234+
ambiguous emphasis ([plan 111][plan111]), and
235+
reference-style links ([plan 107][plan107]).
236+
Image alt text ([MDS032][mds032]) and OL numbering
237+
([MDS046][mds046]) are already implemented.
238+
Teams that need the remaining gaps (space in code,
239+
space in links, proper names, single H1) can pair
240+
mdsmith with markdownlint.
244241

245242
### Prose and Readability
246243

@@ -605,8 +602,10 @@ you need a stable rule set while these land.
605602
[mds028]: ../../internal/rules/MDS028-token-budget/README.md
606603
[mds029]: ../../internal/rules/MDS029-conciseness-scoring/README.md
607604
[mds030]: ../../internal/rules/MDS030-empty-section-body/README.md
605+
[mds032]: ../../internal/rules/MDS032-no-empty-alt-text/README.md
608606
[mds035]: ../../internal/rules/MDS035-toc-directive/README.md
609607
[mds038]: ../../internal/rules/MDS038-toc/README.md
608+
[mds046]: ../../internal/rules/MDS046-ordered-list-numbering/README.md
610609
<!-- markdownlint links -->
611610
[markdownlint]: https://github.com/DavidAnson/markdownlint
612611
[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2

0 commit comments

Comments
 (0)