Skip to content

Ship a shared .markdownlint-cli2.jsonc so derived repos lint consistently (IDE vs CLI) #116

Description

@ptr727

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):

{
    "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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions