[GH-ISSUE #528] `markdownlint-configure-file` Directive Does Not Allow JSON5 Comments

kerem commented

2026-03-07 20:06:15 +03:00

Owner

Originally created by @adam-grant-hendry on GitHub (May 21, 2022).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/528

Adding comments is desirable so the reason why a rule is ignored is documented. However, JSON5-style comments are not parsed by VSCode in file configurations:

Originally created by @adam-grant-hendry on GitHub (May 21, 2022). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/528 Adding comments is desirable so the reason why a rule is ignored is documented. However, JSON5-style comments are not parsed by VSCode in file configurations: ![image](https://user-images.githubusercontent.com/59346180/169662338-ee8b57a0-b99b-43f2-9866-33855cb4155d.png)

kerem

2026-03-07 20:06:15 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-07 20:06:16 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (May 21, 2022):

@DavidAnson Do I need to move this to vscode-markdownlint?

@adam-grant-hendry commented on GitHub (May 21, 2022): @DavidAnson Do I need to move this to [vscode-markdownlint](https://github.com/DavidAnson/vscode-markdownlint/issues?q=is%3Aopen+is%3Aissue)?

kerem commented

2026-03-07 20:06:16 +03:00

Author

Owner

@DavidAnson commented on GitHub (May 21, 2022):

No, this is the right place. I'll probably do this soon for the upcoming release.

@DavidAnson commented on GitHub (May 21, 2022): No, this is the right place. I'll probably do this soon for the upcoming release.

kerem commented

2026-03-07 20:06:16 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (May 22, 2022):

@DavidAnson Okay, no problem. Thanks!

@adam-grant-hendry commented on GitHub (May 22, 2022): @DavidAnson Okay, no problem. Thanks!

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (Oct 5, 2022):

@DavidAnson This fixes the issue in VSCode, but pre-commit issues an error when comments are used. Do you have a recommendation?

@adam-grant-hendry commented on GitHub (Oct 5, 2022): @DavidAnson This fixes the issue in VSCode, but `pre-commit` issues an error when comments are used. Do you have a recommendation?

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 5, 2022):

Is pre-commit itself emitting an error, or is a tool it runs doing so? If the latter, make sure it's using the latest version of markdownlint with support for JSONC.

@DavidAnson commented on GitHub (Oct 5, 2022): Is pre-commit itself emitting an error, or is a tool it runs doing so? If the latter, make sure it's using the latest version of markdownlint with support for JSONC.

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (Oct 5, 2022):

Oh good call: I was using https://github.com/igorshubovych/markdownlint-cli in pre-commit. Maybe that repo isn't up-to-date with yours...?

Should I run this as a local hook instead, or is there a preferred repo to use? I see there is -cli and -cli2, for instance.

@adam-grant-hendry commented on GitHub (Oct 5, 2022): Oh good call: I was using https://github.com/igorshubovych/markdownlint-cli in `pre-commit`. Maybe that repo isn't up-to-date with yours...? Should I run this as a local hook instead, or is there a preferred repo to use? [I see](https://github.com/DavidAnson/markdownlint-cli2#overview) there is `-cli` and `-cli2`, for instance.

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 5, 2022):

The latest version of both CLIs have support for JSONC, but probably only the latest version. Depending on how you are referencing it from pre-commit, you might not be getting that? I might be able to tell from looking at an example.

@DavidAnson commented on GitHub (Oct 5, 2022): The latest version of both CLIs have support for JSONC, but probably only the latest version. Depending on how you are referencing it from pre-commit, you might not be getting that? I might be able to tell from looking at an example.

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (Oct 6, 2022):

@DavidAnson Here is what is happening. As you can see, VSCode gives no linting errors, but pre-commit running markdownlint-cli is still outputting an error:

@adam-grant-hendry commented on GitHub (Oct 6, 2022): @DavidAnson Here is what is happening. As you can see, VSCode gives no linting errors, but pre-commit running `markdownlint-cli` is still outputting an error: ![image](https://user-images.githubusercontent.com/59346180/194429689-3db756b2-25a7-484d-914a-006bad42a6d6.png)

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (Oct 6, 2022):

@DavidAnson Here is my .pre-commit-config.yml file:

fail_fast: true
repos:
    # `markdownlint` is only available through npm (Node.js), not pip (PyPI).
  - repo: https://github.com/igorshubovych/markdownlint-cli
    rev: v0.32.2
    hooks:
      - id: markdownlint
        name: (markdownlint) Check Markdown syntax
        args: ["--config=.markdownlint.yml"]

and the content of my CHANGELOG.md:

<!-- markdownlint-configure-file
{
    "MD024": false  // Allow multiple headings with the same name
}
-->
## 0.2.0 (2022-10-06)

### Feat

- **ci**: update `commitizen` settings and `pypi` uploading (#7)
- **ci**: modify cache configuration
- **ci**: add headless display action to `test.yml` (#3)
- **ci**: add tox to github actions

### Fix

- **ci**: correct pypi password environment variable in release job (#6)
- **ci**: change concurrency group to use context variables (#4)

## 0.1.0 (2022-09-24)

### Feat

- **init**: initial commit

@adam-grant-hendry commented on GitHub (Oct 6, 2022): @DavidAnson Here is my `.pre-commit-config.yml` file: ```yaml fail_fast: true repos: # `markdownlint` is only available through npm (Node.js), not pip (PyPI). - repo: https://github.com/igorshubovych/markdownlint-cli rev: v0.32.2 hooks: - id: markdownlint name: (markdownlint) Check Markdown syntax args: ["--config=.markdownlint.yml"] ``` and the content of my `CHANGELOG.md`: ```markdown  ## 0.2.0 (2022-10-06) ### Feat - **ci**: update `commitizen` settings and `pypi` uploading (#7) - **ci**: modify cache configuration - **ci**: add headless display action to `test.yml` (#3) - **ci**: add tox to github actions ### Fix - **ci**: correct pypi password environment variable in release job (#6) - **ci**: change concurrency group to use context variables (#4) ## 0.1.0 (2022-09-24) ### Feat - **init**: initial commit ```

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (Oct 6, 2022):

@DavidAnson My .markdownlint.yml is:

# Default state for all rules
default: true

# Disable line length too long
#  - Ouptut looks bad with broken lines
#  - VSCode can wrap text
MD013: false

# Allow inline HTML
#  - `markdownlint` enforces this rule for those who want their documents to be pure
#    Markdown, but raw HTML is allowed in Markdown
#  - HTML sometimes help us acheive things Markdown itself cannot
MD033: false

# Allow non-headings for first line in file
#  - Sometimes we want comments or HTML before our first header
MD041: false

If I remove the comment in my CHANGELOG.md, then pre-commit passes:

@adam-grant-hendry commented on GitHub (Oct 6, 2022): @DavidAnson My `.markdownlint.yml` is: ```yaml # Default state for all rules default: true # Disable line length too long # - Ouptut looks bad with broken lines # - VSCode can wrap text MD013: false # Allow inline HTML # - `markdownlint` enforces this rule for those who want their documents to be pure # Markdown, but raw HTML is allowed in Markdown # - HTML sometimes help us acheive things Markdown itself cannot MD033: false # Allow non-headings for first line in file # - Sometimes we want comments or HTML before our first header MD041: false ``` If I remove the comment in my `CHANGELOG.md`, then `pre-commit` passes: ![image](https://user-images.githubusercontent.com/59346180/194431444-26f08f94-f72e-4457-b6b7-4af997303ef9.png)

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 6, 2022):

I don't spot the problem on visual inspection. However, I do not understand your last message that removing the comment gets pre-commit to pass. For one, I still see the comment at the top of the file in your screenshot, and for another, I thought pre-commit was only supposed to pass if that comment was present (i.e., the rule is disabled).

Is this repository public?

@DavidAnson commented on GitHub (Oct 6, 2022): I don't spot the problem on visual inspection. However, I do not understand your last message that removing the comment gets pre-commit to pass. For one, I still see the comment at the top of the file in your screenshot, and for another, I thought pre-commit was only supposed to pass if that comment was present (i.e., the rule is disabled). Is this repository public?

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@adam-grant-hendry commented on GitHub (Oct 6, 2022):

I do not understand your last message that removing the comment gets pre-commit to pass.

The JSON comment, not the HTML comment. Above was changed from

<!-- markdownlint-configure-file
{
    "MD024": false  // Allow multiple headings with the same name
}
-->

to

<!-- markdownlint-configure-file
{
    "MD024": false 
}
-->

Is this repository public?

Yes: it is called qtpygraph. Please feel free to take a look: https://github.com/adam-grant-hendry/qtpygraph.

@adam-grant-hendry commented on GitHub (Oct 6, 2022): > I do not understand your last message that removing the comment gets pre-commit to pass. The JSON comment, not the HTML comment. Above was changed from ```html  ``` to ```html  ``` > Is this repository public? Yes: it is called `qtpygraph`. Please feel free to take a look: https://github.com/adam-grant-hendry/qtpygraph.

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 7, 2022):

@adam-grant-hendry, your scenario in your repo seems to work fine for me in a GitHub Codespace:

@DavidAnson ➜ /workspaces/qtpygraph (main) $ git status
On branch main
Your branch is up to date with 'origin/main'.

Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
        modified:   CHANGELOG.md

@DavidAnson ➜ /workspaces/qtpygraph (main) $ git diff --cached 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b6f33f..aeb33ac 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,3 +8,9 @@
 ### Feat
 
 - **init**: initial commit
+
+## 0.1.0 (2022-09-24)
+
+### Feat
+
+- **init**: initial commit
@DavidAnson ➜ /workspaces/qtpygraph (main) $ pre-commit run markdownlint
(markdownlint) Check Markdown syntax.....................................Passed
@DavidAnson ➜ /workspaces/qtpygraph (main) $

And after breaking the JSONC disable:

@DavidAnson ➜ /workspaces/qtpygraph (main) $ git diff --cached 
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9b6f33f..4ca708a 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,6 @@
 <!-- markdownlint-configure-file
 {
-    "MD024": false
+    "MD024x": false
 }
 -->
 ## 0.1.0 (2022-09-24)
@@ -8,3 +8,9 @@
 ### Feat
 
 - **init**: initial commit
+
+## 0.1.0 (2022-09-24)
+
+### Feat
+
+- **init**: initial commit
@DavidAnson ➜ /workspaces/qtpygraph (main) $ pre-commit run markdownlint
(markdownlint) Check Markdown syntax.....................................Failed
- hook id: markdownlint
- exit code: 1

CHANGELOG.md:12 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "## 0.1.0 (2022-09-24)"]
CHANGELOG.md:14 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Feat"]

@DavidAnson ➜ /workspaces/qtpygraph (main) $

@DavidAnson commented on GitHub (Oct 7, 2022): @adam-grant-hendry, your scenario in your repo seems to work fine for me in a GitHub Codespace: ```bash @DavidAnson ➜ /workspaces/qtpygraph (main) $ git status On branch main Your branch is up to date with 'origin/main'. Changes to be committed: (use "git restore --staged <file>..." to unstage) modified: CHANGELOG.md @DavidAnson ➜ /workspaces/qtpygraph (main) $ git diff --cached diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b6f33f..aeb33ac 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,3 +8,9 @@ ### Feat - **init**: initial commit + +## 0.1.0 (2022-09-24) + +### Feat + +- **init**: initial commit @DavidAnson ➜ /workspaces/qtpygraph (main) $ pre-commit run markdownlint (markdownlint) Check Markdown syntax.....................................Passed @DavidAnson ➜ /workspaces/qtpygraph (main) $ ``` And after breaking the JSONC disable: ```bash @DavidAnson ➜ /workspaces/qtpygraph (main) $ git diff --cached diff --git a/CHANGELOG.md b/CHANGELOG.md index 9b6f33f..4ca708a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@  ## 0.1.0 (2022-09-24) @@ -8,3 +8,9 @@ ### Feat - **init**: initial commit + +## 0.1.0 (2022-09-24) + +### Feat + +- **init**: initial commit @DavidAnson ➜ /workspaces/qtpygraph (main) $ pre-commit run markdownlint (markdownlint) Check Markdown syntax.....................................Failed - hook id: markdownlint - exit code: 1 CHANGELOG.md:12 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "## 0.1.0 (2022-09-24)"] CHANGELOG.md:14 MD024/no-duplicate-heading/no-duplicate-header Multiple headings with the same content [Context: "### Feat"] @DavidAnson ➜ /workspaces/qtpygraph (main) $ ```

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@nschonni commented on GitHub (Oct 7, 2022):

I think if I had to rename the title of this to be clearer, it would be "markdownlint-configure-file directive does not allow JSON comments". @DavidAnson you're test was just for the markdownlint-configure-file, not the part that was breaking above, when a comment is included into an already valid directive

@nschonni commented on GitHub (Oct 7, 2022): I think if I had to rename the title of this to be clearer, it would be "markdownlint-configure-file directive does not allow JSON comments". @DavidAnson you're test was just for the `markdownlint-configure-file`, not the part that was breaking above, when a comment is included into an already valid directive

kerem commented

2026-03-07 20:06:17 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 7, 2022):

Understood, thanks! I will try again tomorrow.

@DavidAnson commented on GitHub (Oct 7, 2022): Understood, thanks! I will try again tomorrow.

kerem commented

2026-03-07 20:06:18 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 8, 2022):

So, ha ha, funny story... While most changes to the markdownlint library automatically show up in the CLIs, this one does not. markdownlint-cli is missing a commit like this one to use the new configParsers option to support JSONC inside markdownlint-configure-file. @adam-grant-hendry, could you please open an issue in that repo for this task? https://github.com/igorshubovych/markdownlint-cli/issues

Sorry for the confusion.

@DavidAnson commented on GitHub (Oct 8, 2022): So, ha ha, funny story... While _most_ changes to the `markdownlint` library automatically show up in the CLIs, this one does not. `markdownlint-cli` is missing a commit like [this one](https://github.com/DavidAnson/markdownlint-cli2/commit/8b1eee07bf00a18ae864236db918a05cfd6cbe5d) to use the new `configParsers` option to support JSONC inside `markdownlint-configure-file`. @adam-grant-hendry, could you please open an issue in that repo for this task? https://github.com/igorshubovych/markdownlint-cli/issues Sorry for the confusion.

kerem commented

2026-03-07 20:06:18 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 8, 2022):

Nevermind, here's the fix for markdownlint-cli: github.com/igorshubovych/markdownlint-cli@40c1734aa8

@DavidAnson commented on GitHub (Oct 8, 2022): Nevermind, here's the fix for `markdownlint-cli`: https://github.com/igorshubovych/markdownlint-cli/commit/40c1734aa83c4ddedf5b3f934e858160627074cc

kerem commented

2026-03-07 20:06:18 +03:00

Author

Owner

@DavidAnson commented on GitHub (Oct 8, 2022):

If you want something that works right now, CLI2 is also configured to support pre-commit.

@DavidAnson commented on GitHub (Oct 8, 2022): If you want something that works right now, CLI2 is also configured to support pre-commit.

Rows
Columns

[GH-ISSUE #528] markdownlint-configure-file Directive Does Not Allow JSON5 Comments #2279

[GH-ISSUE #528] `markdownlint-configure-file` Directive Does Not Allow JSON5 Comments #2279