starred/markdownlint

Fork 0

mirror of https://github.com/DavidAnson/markdownlint.git synced 2026-04-25 17:26:22 +03:00

[GH-ISSUE #1397] `.markdownlint.jsonc` config `json-schema.org` schema: allow trailing commas #2526

New issue

Closed

opened 2026-03-07 20:08:34 +03:00 by kerem · 3 comments

kerem commented

2026-03-07 20:08:34 +03:00

Owner

Originally created by @jimmy-zhening-luo on GitHub (Oct 31, 2024).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1397

Problem Statement

Edit a .markdownlint.jsonc file in VSCode.
Manually specify $schema as good practice:

{
  "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.36.1/schema/markdownlint-config-schema.json",
}

Verify that trailing commas are allowed, because markdownlint happily accepts a .jsonc config with trailing commas.

Expected

VSCode does not show any warning about trailing commas.

Actual

VSCode shows warnings about trailing commas.

Mitigation

In .markdownlint.jsonc, comment out $schema field:

{
  // "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.36.1/schema/markdownlint-config-schema.json",
}

By default, VSCode complains about trailing commas in any jsonc file unless told otherwise by a $schema. To allow commas unles told otherwise by a $schema, add this to your VSCode user or workspace settings.json:

{
  "json.schemas": [{
    "fileMatch": ["**/*.jsonc"] /* array of patterns to match, where here I prefer a block-list approach when it comes to .jsonc */,
    "schema": {
      "allowTrailingCommas": true,
    },
  }],
}

Voila!

And, miraculously, VSCode still validates schema even without $schema, either because of DavidAnson's extension is smartly doing some file association, or because VSCode Markdown Language Support is auto-magic (I haven't checked yet 😅, but I'm assuming the former because anyone fastidious enough to ship a json-schema.org schema would probably do that).

Proposed Change

Create a json-schema.org schema for .markdownlint.jsonc with { "allowTrailingCommas": true }.

Rationale

When a $schema is specified in a JSONC object, VScode treats that schema as the source of truth. Additionally, per Microsoft/VSCode#102061 (comment-656541600), VSCode will never allow trailing commas in a JSONC file unless that source of truth says { "allowTrailingCommas": true }.

N.B. Because markdownlint also supports .markdownlint.json configs (I think), perhaps this require a split between the .json and .jsonc schemas, where the .jsonc schema allows trailing commas (per observed behavior from markdownlint's jsonc config parser), whereas a .json schema of course should never allow trailing commas.

Originally created by @jimmy-zhening-luo on GitHub (Oct 31, 2024). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/1397 # Problem Statement 1. Edit a `.markdownlint.jsonc` file in `VSCode`. 2. Manually specify `$schema` as good practice: ```jsonc { "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.36.1/schema/markdownlint-config-schema.json", } ``` 3. Verify that trailing commas are allowed, because `markdownlint` happily accepts a `.jsonc` config with trailing commas. ## Expected VSCode does not show any warning about trailing commas. ## Actual VSCode shows warnings about trailing commas. ![image](https://github.com/user-attachments/assets/c5acd249-27f2-4625-a95a-30defd67364f) ![image](https://github.com/user-attachments/assets/0b5e01cf-c8f5-4c8c-9e2d-2516bf01da8a) ### Mitigation 1. In `.markdownlint.jsonc`, comment out `$schema` field: ```jsonc { // "$schema": "https://raw.githubusercontent.com/DavidAnson/markdownlint/v0.36.1/schema/markdownlint-config-schema.json", } ``` 2. By default, VSCode complains about trailing commas in any `jsonc` file __unless told otherwise by a `$schema`__. To allow commas unles told otherwise by a `$schema`, add this to your VSCode user or workspace `settings.json`: ```jsonc { "json.schemas": [{ "fileMatch": ["**/*.jsonc"] /* array of patterns to match, where here I prefer a block-list approach when it comes to .jsonc */, "schema": { "allowTrailingCommas": true, }, }], } ``` Voila! ![image](https://github.com/user-attachments/assets/6fdfc629-ea83-4e7c-8daf-231c7f5d93c4) And, miraculously, __VSCode still validates schema even without `$schema`__, either because of DavidAnson's extension is smartly doing some file association, or because VSCode Markdown Language Support is auto-magic (I haven't checked yet 😅, but I'm assuming the former because anyone fastidious enough to ship a `json-schema.org` schema would probably do that). ![image](https://github.com/user-attachments/assets/7a7fb9ee-f29a-4cdb-bdd5-8a52ae4df1db) # Proposed Change Create a `json-schema.org` schema for `.markdownlint.jsonc` with `{ "allowTrailingCommas": true }`. ## Rationale When a `$schema` is specified in a JSONC object, VScode treats that schema as the source of truth. Additionally, per Microsoft/VSCode#102061 ([comment-656541600](https://github.com/microsoft/vscode/issues/102061#issuecomment-656541600)), VSCode will never allow trailing commas in a JSONC file unless that source of truth says `{ "allowTrailingCommas": true }`. N.B. Because `markdownlint` also supports `.markdownlint.json` configs (I think), perhaps this require a split between the `.json` and `.jsonc` schemas, where the `.jsonc` schema allows trailing commas (per observed behavior from `markdownlint`'s `jsonc` config parser), whereas a `.json` schema of course should never allow trailing commas.

kerem

2026-03-07 20:08:34 +03:00

closed this issue
added the
question
label

kerem commented

2026-03-07 20:08:35 +03:00

Author

Owner

@DavidAnson commented on GitHub (Nov 1, 2024):

First off, thank you for a very well-written and documented issue! It is a pleasure to get issues where people have done their homework. :)

That said, there is already a discussion of this topic which explains why I do NOT think modifying the schema file is appropriate: https://github.com/DavidAnson/markdownlint-cli2/pull/270

That said, I agree that parsers should allow trailing commas for flexibility and that's why markdownlint handles with or without: github.com/DavidAnson/markdownlint-cli2@da711fa8b3/parsers/jsonc-parse.js (L14)

@DavidAnson commented on GitHub (Nov 1, 2024): First off, thank you for a very well-written and documented issue! It is a pleasure to get issues where people have done their homework. :) That said, there is already a discussion of this topic which explains why I do NOT think modifying the schema file is appropriate: https://github.com/DavidAnson/markdownlint-cli2/pull/270 That said, I agree that parsers should allow trailing commas for flexibility and that's why markdownlint handles with or without: https://github.com/DavidAnson/markdownlint-cli2/blob/da711fa8b30421506086eb2dc7ea0a6c3cb27b9f/parsers/jsonc-parse.js#L14

kerem commented

2026-03-07 20:08:36 +03:00

Author

Owner

@jimmy-zhening-luo commented on GitHub (Nov 1, 2024):

Thank you for taking the time to respond!

I agree with your reasoning for not changing it and am actually starting to come around myself. In the meantime, it's beneficial to me that you decided to have your config parser gracefully handle with or without trailing commas. I'll close this request now since given the prior art I missed and since I agree with the prior resolution.

Thanks again, I'm a big fan of your work, you've made writing/editing/coding in Markdown sane in a way I haven't seen done elsewhere.

@jimmy-zhening-luo commented on GitHub (Nov 1, 2024): Thank you for taking the time to respond! I agree with your reasoning for not changing it and am actually starting to come around myself. In the meantime, it's beneficial to me that you decided to have your config parser gracefully handle with or without trailing commas. I'll close this request now since given the prior art I missed and since I agree with the prior resolution. Thanks again, I'm a big fan of your work, you've made writing/editing/coding in Markdown sane in a way I haven't seen done elsewhere.

kerem commented

2026-03-07 20:08:36 +03:00

Author

Owner

@DavidAnson commented on GitHub (Nov 1, 2024):

Cheers! :)

@DavidAnson commented on GitHub (Nov 1, 2024): Cheers! :)