Repository navigation
Description
Summary
ProjectTemplate's workspaces recommend the davidanson.vscode-markdownlint
extension, but the template ships no markdownlint configuration. As a result,
every derived repo gets inconsistent lint behavior: the IDE extension and any
command-line / CI run of markdownlint-cli2 apply different rule sets, and each
downstream repo has to (re)invent its own config from scratch.
Evidence
DotNet.code-workspace:95andPython.code-workspace:95both list
"davidanson.vscode-markdownlint"under recommended extensions.- There is no
.markdownlint-cli2.jsonc/.markdownlint.json/.markdownlintrc
anywhere in the template (root or per-language project dirs).
Why this causes drift
markdownlint-cli2 and the davidanson VS Code extension both read a
.markdownlint-cli2.jsonc config file. With none present:
- The extension falls back to its bundled defaults (or a developer's personal
user-settings config), while a CLI/CI invocation falls back to the tool
defaults — they don't have to match. - Style-heavy docs trip default rules that the maintainer intentionally does not
enforce. Concretely, in a derived repo (ptr727/KiCadLibrary) a CLI run
reported 46 MD013/line-length errors on aREADME.mdthat the IDE showed
as clean, purely because no shared config disabled MD013. - Each repo solves this independently.
ptr727/homeassistant-purpleairalready
carries a hand-tuned.markdownlint-cli2.jsonc; KiCadLibrary had none until I
copied that file in. That's exactly the kind of per-repo divergence the
template exists to prevent.
Recommendation
Ship a single source-of-truth .markdownlint-cli2.jsonc at the template root
(and in each per-language project dir if those are templated independently).
Because the one file is honored by both the extension and the CLI/CI, the IDE and
the command line stay in lock-step. Suggested content (mirrors the de-facto
standard already used in homeassistant-purpleair):
{
"config": {
// Prose paragraphs and data-heavy tables/URLs are intentionally long;
// reflowing at 80 cols hurts readability and churns diffs.
"MD013": false,
// Inline HTML is used for reference-link section dividers.
"MD033": false,
// Require fenced code blocks over the legacy 4-space-indented style.
"MD046": { "style": "fenced" },
// Wide tables are intentional where wrapping cells breaks GitHub rendering.
"MD060": false
},
"gitignore": true
}Optionally, add a one-line note to CODESTYLE.md / AGENTS.md stating that the
authoritative lint result is what this config produces (so contributors don't
"fix" rules the project has deliberately turned off), and wire
markdownlint-cli2 into the lint task / CI so the gate matches the IDE.
Activity
Propagate template contract to derived repos: lint config, review-loo…
Propagate template contract to derived repos and roll up codegen (#125)