Extend Markdown linters comparison page and link from README - #204
Conversation
|
Use front matter and then use to link the doc in readme. This is to ensure the description is colocated with the content. |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #204 +/- ##
=======================================
Coverage 94.10% 94.10%
=======================================
Files 132 132
Lines 14725 14725
=======================================
Hits 13857 13857
Misses 528 528
Partials 340 340 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
There was a problem hiding this comment.
Pull request overview
Expands mdsmith’s documentation comparing it to other Markdown tools (including Hugo, query, security posture, and future plans) and makes that comparison easier to discover from the README.
Changes:
- Added a Hugo entry and a Hugo-vs-mdsmith generated-content comparison table to the linters comparison page.
- Documented
mdsmith query, added a security posture comparison section, and linked relevant plans and references. - Added a “How does it compare?” callout in the README linking to the comparison page.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/background/markdown-linters.md | Adds Hugo, query, security posture, future plans, and supporting reference links. |
| README.md | Adds a prominent link/callout to the comparison page after “Why mdsmith”. |
There was a problem hiding this comment.
Pull request overview
Expands the Markdown linters comparison doc to cover additional tools/capabilities (including Hugo, security posture, and future plans) and adds a prominent README link to that comparison so users can quickly evaluate mdsmith against alternatives.
Changes:
- Added a Hugo comparison subsection, expanded the structural linting matrix, and updated the structural summary narrative.
- Added new sections covering security posture and future plans, with plan/doc link references.
- Linked the comparison page from README.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
| docs/background/markdown-linters.md | Extends and restructures the comparison content; adds Hugo + security posture + future plans; adds new rule/plan link refs. |
| README.md | Adds a “How does it compare?” callout linking to the comparison doc. |
|
@copilot apply changes based on the comments in this thread and include obsidian |
Done in 2a871e1. The README "How does it compare?" callout now uses a
Done in 2a871e1. Applied all three review-thread fixes (alias rejection cell, sanitization spelling, artifacts spelling) and added an Obsidian subsection in Tool Overview covering wikilinks/callouts/linting/front matter/agent-friendliness with a comparison table. |
There was a problem hiding this comment.
Pull request overview
Expands the repository’s “Markdown linters comparison” documentation and surfaces it from top-level entry points, while adding new plan documents for upcoming link-reference integrity rules (MD052/MD053 parity).
Changes:
- Added plans for MDS052 (undefined reference labels) and MDS053 (unused/duplicate link reference definitions), plus additional upcoming rule plans.
- Expanded
docs/background/markdown-linters.mdwith new tool sections (Hugo, Obsidian), a security posture section, and updated comparison tables. - Linked the comparison page from
README.mdand refreshed generated catalogs in contributor instruction files; regeneratedPLAN.mdto include the new plans.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| plan/124_no-space-in-code-spans.md | New plan for MDS048 (space in code spans). |
| plan/125_no-space-in-link-text.md | New plan for MDS049 (space in link text). |
| plan/126_proper-names.md | New plan for MDS050 (proper-name capitalization). |
| plan/127_single-h1.md | New plan for MDS051 (single H1). |
| plan/128_no-undefined-reference-labels.md | New plan for MDS052 (undefined reference labels). |
| plan/129_no-unused-link-definitions.md | New plan for MDS053 (unused/duplicate link reference definitions). |
| docs/background/markdown-linters.md | Expanded comparison content; updated summary used by catalogs; added security posture and future plans sections. |
| README.md | Added a catalog-backed link to the comparison page. |
| PLAN.md | Regenerated plan catalog to include new plans. |
| CLAUDE.md | Updated catalog entry text for the comparison page. |
| AGENTS.md | Updated catalog entry text for the comparison page. |
| .github/copilot-instructions.md | Updated catalog entry text for the comparison page. |
Comments suppressed due to low confidence (1)
docs/background/markdown-linters.md:174
- The LLM discussion under “Tool Overview” no longer has a
### LLM as Linterheading (it currently starts with a paragraph after the Obsidian section). Add back an h3 heading so this section remains scannable and consistent with the other tool subsections.
Using language models (GPT-4, Claude, etc.) directly to
check prose quality, conciseness, and style. This is
emerging through dedicated CLI tools and AI review bots.
|
@copilot apply changes based on the comments in this thread |
Applied all seven items from that thread in 9d45f44: removed the invalid |
Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/71eb11d4-360d-4297-8a26-1800769b40ae Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
…ations Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/bb8f681c-272f-45b5-90e0-70c7aed81522 Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
…sues; add Obsidian Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/3991a7bc-82a8-4cb8-bcc2-78a21b8fe49a Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
…nks, proper-names, single-H1) Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/86a0ecef-882c-4f8e-b485-e94e86adbad1 Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/60d0ccb6-54d1-4e76-8ef2-45e329bf398b Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
Agent-Logs-Url: https://github.com/jeduden/mdsmith/sessions/9c7474b1-6cbb-474a-a72d-9f8390848936 Co-authored-by: jeduden <1117699+jeduden@users.noreply.github.com>
9d45f44 to
b9c4d2d
Compare
There was a problem hiding this comment.
Pull request overview
This PR expands the project’s “Markdown linters comparison” documentation and makes it discoverable from the README, while also adding/including new plan documents that the comparison page links to (notably for proposed MD052/MD053 parity rules).
Changes:
- Extend
docs/background/markdown-linters.mdwith additional tool comparisons (e.g., Hugo, Obsidian), a security posture section, and updated capability tables/plan links. - Add a generated link to the comparison page from
README.md. - Add new plan documents (124–129) and regenerate
PLAN.mdso the plan catalog includes them; update generated doc catalogs to use the new comparison-page summary text.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| plan/124_no-space-in-code-spans.md | New plan document referenced from the comparison page’s capability table. |
| plan/125_no-space-in-link-text.md | New plan document referenced from the comparison page’s capability table. |
| plan/126_proper-names.md | New plan document referenced from the comparison page’s capability table. |
| plan/127_single-h1.md | New plan document referenced from the comparison page’s capability table. |
| plan/128_no-undefined-reference-labels.md | New plan for an MD052-equivalent rule, referenced from the comparison page. |
| plan/129_no-unused-link-definitions.md | New plan for an MD053-equivalent rule, referenced from the comparison page. |
| docs/background/markdown-linters.md | Main expansion: new tool sections, updated structural linting table, security posture, and refreshed link references. |
| README.md | Adds a generated catalog/link pointing readers to the comparison page. |
| PLAN.md | Regenerated plan catalog to include plans 124–129. |
| CLAUDE.md | Updates the generated docs catalog entry text for the comparison page. |
| AGENTS.md | Updates the generated docs catalog entry text for the comparison page. |
| .github/copilot-instructions.md | Updates the generated docs catalog entry text for the comparison page. |
Comments suppressed due to low confidence (1)
docs/background/markdown-linters.md:176
- The LLM section lost its heading: after the Obsidian section, the text starting with "Using language models…" is now part of the Obsidian section because there’s no new
###header. Reintroduce a### LLM as Linter(or similar) heading before this paragraph so the document structure/TOC matches the intent.
Using language models (GPT-4, Claude, etc.) directly to
check prose quality, conciseness, and style. This is
emerging through dedicated CLI tools and AI review bots.
How it works:
*ast.Linkonly; goldmark drops undefined[text][label]to plain text and never visits unreferenced link definitions)docs/background/markdown-linters.mdplan/124_no-space-in-code-spans.md(MDS038-equivalent rule)plan/125_no-space-in-link-text.md(MDS039-equivalent rule)plan/126_no-trailing-punctuation-in-headings.md(MDS026-equivalent rule)plan/127_single-h1.md(MDS025-equivalent rule)plan/128_no-undefined-reference-labels.md(MDS052-equivalent rule)plan/129_no-unused-link-definitions.md(MDS053-equivalent rule)PLAN.mdcatalog so the new plans appearenabled:keys from rule config snippets in plans 124/125/127/128/129; lowercase theh1 heading conflicts with front-matter titleexample in plan 127; Americannormalizationspellingmdsmith checkclean for the new and modified files (pre-existing MDS026 width warning onPLAN.mdis unchanged)