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:95 and Python.code-workspace:95 both 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 a README.md that the IDE showed
as clean, purely because no shared config disabled MD013.
- Each repo solves this independently.
ptr727/homeassistant-purpleair already
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):
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.
Summary
ProjectTemplate's workspaces recommend the
davidanson.vscode-markdownlintextension, 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-cli2apply different rule sets, and eachdownstream 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..markdownlint-cli2.jsonc/.markdownlint.json/.markdownlintrcanywhere in the template (root or per-language project dirs).
Why this causes drift
markdownlint-cli2and the davidanson VS Code extension both read a.markdownlint-cli2.jsoncconfig file. With none present:user-settings config), while a CLI/CI invocation falls back to the tool
defaults — they don't have to match.
enforce. Concretely, in a derived repo (
ptr727/KiCadLibrary) a CLI runreported 46 MD013/line-length errors on a
README.mdthat the IDE showedas clean, purely because no shared config disabled MD013.
ptr727/homeassistant-purpleairalreadycarries a hand-tuned
.markdownlint-cli2.jsonc; KiCadLibrary had none until Icopied 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.jsoncat 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.mdstating that theauthoritative lint result is what this config produces (so contributors don't
"fix" rules the project has deliberately turned off), and wire
markdownlint-cli2into the lint task / CI so the gate matches the IDE.