[GH-ISSUE #118] feature_request(configuration): support YAML configuration format

kerem commented

2026-03-07 20:03:01 +03:00

Owner

Originally created by @Kristinita on GitHub (Apr 17, 2018).
Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/118

1. Summary

It would be nice, if Markdownlint will support configuration file in YAML format.

2. Argumentation

2.1. Comments

I can't use comments in .markdownlintrc.

I think, that comment, why I use this or that option, is a nice practice. My .markdownlintrc file:

{
    //////////////////
    // Markdownlint //
    //////////////////
    // Lint Markdown files:
    // https://www.npmjs.com/package/markdownlint
    // Ruby Markdownlint obsolete, have bugs (see comments below)
    // and doesn't support at the time:
    // https://rubygems.org/gems/mdl
    // Markdownlint styles:
    // Rules: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md
    //
    //
    // [DEPRECATED] In my Pelican articles I use h1 tag in page templates
    // I begin section use h2 tag
    // Using h1 tag is good — http://archive.li/X3d8c
    // Enable, because downheader extension
    // https://github.com/cprieto/mdx_downheader
    // "MD002": false,
    // [WARNING] Rule only for spaces indentation, show errors, if using tabs. So exclude.
    "MD007": false,
    // Allowed 2 trailing spaces in line, not 1, 3 or 4:
    // https://github.com/markdownlint/markdownlint/issues/165
    "MD009": {
        "br_spaces": 2
    },
    // I prefer tabs instead of spaces:
    // https://softwareengineering.stackexchange.com/a/72/264224
    "MD010": false,
    // [DEPRECATED] In my Pelican articles I use h1 tag in page templates
    // I begin section use h2 tag
    // Using h1 tag is good — http://archive.li/X3d8c
    // Enable, because downheader extension
    // https://github.com/cprieto/mdx_downheader
    // exclude_rule 'MD0102'
    "MD013": false,
    // I use MarkdownTOC autoanchoring:
    // https://github.com/naokazuterada/MarkdownTOC#auto-anchoring-when-heading-has-anchor-defined
    "MD022": false,
    // [DONE] This option works in Node Markdownlint, not Ruby mdl:
    // I end headers with question marks:
    // [BUG] Doesn't work, if inline HTML:
    // https://github.com/markdownlint/markdownlint/issues/196
    "MD026": {
        "punctuation": ".,;:!"
    },
    // Pelican features needs inline HTML support
    "MD033": false,
    // I use bare URL for Pelican article metadata variable “Opengraphimage”.
    // Open Graph — http://ruogp.me/
    // Also, I use bare URL for magiclink:
    // http://facelessuser.github.io/pymdown-extensions/extensions/magiclink/
    "MD034": false,
    // [DONE] This option works in Node Markdownlint, not Ruby mdl:
    // [BUG] Temporary exclude rule before the new release:
    // https://github.com/mivok/markdownlint/pull/160
    // "MD039": false,
    // In Pelican articles and pages first line — is Metadata, not header
    "MD041": false
}

I use grunt-markdownlint plugin. It supports JSON configuration file:

example2: {
  options: {
    config: grunt.file.readJSON(rulesFile) //read linting rules from file
  }

grunt.file.readJSON doesn't support comments in .markdownlintrc file → I can't use comments in .markdownlintrc.

Grunt support parsing YAML data.

2.2. Another reasons

JSON as configuration files: please don't

Thanks.

Originally created by @Kristinita on GitHub (Apr 17, 2018). Original GitHub issue: https://github.com/DavidAnson/markdownlint/issues/118 ### 1. Summary It would be nice, if Markdownlint will support configuration file in YAML format. ### 2. Argumentation #### 2.1. Comments I can't use comments in `.markdownlintrc`. I think, that comment, why I use this or that option, is a nice practice. My `.markdownlintrc` file: ```javascript { ////////////////// // Markdownlint // ////////////////// // Lint Markdown files: // https://www.npmjs.com/package/markdownlint // Ruby Markdownlint obsolete, have bugs (see comments below) // and doesn't support at the time: // https://rubygems.org/gems/mdl // Markdownlint styles: // Rules: https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md // // // [DEPRECATED] In my Pelican articles I use h1 tag in page templates // I begin section use h2 tag // Using h1 tag is good — http://archive.li/X3d8c // Enable, because downheader extension // https://github.com/cprieto/mdx_downheader // "MD002": false, // [WARNING] Rule only for spaces indentation, show errors, if using tabs. So exclude. "MD007": false, // Allowed 2 trailing spaces in line, not 1, 3 or 4: // https://github.com/markdownlint/markdownlint/issues/165 "MD009": { "br_spaces": 2 }, // I prefer tabs instead of spaces: // https://softwareengineering.stackexchange.com/a/72/264224 "MD010": false, // [DEPRECATED] In my Pelican articles I use h1 tag in page templates // I begin section use h2 tag // Using h1 tag is good — http://archive.li/X3d8c // Enable, because downheader extension // https://github.com/cprieto/mdx_downheader // exclude_rule 'MD0102' "MD013": false, // I use MarkdownTOC autoanchoring: // https://github.com/naokazuterada/MarkdownTOC#auto-anchoring-when-heading-has-anchor-defined "MD022": false, // [DONE] This option works in Node Markdownlint, not Ruby mdl: // I end headers with question marks: // [BUG] Doesn't work, if inline HTML: // https://github.com/markdownlint/markdownlint/issues/196 "MD026": { "punctuation": ".,;:!" }, // Pelican features needs inline HTML support "MD033": false, // I use bare URL for Pelican article metadata variable “Opengraphimage”. // Open Graph — http://ruogp.me/ // Also, I use bare URL for magiclink: // http://facelessuser.github.io/pymdown-extensions/extensions/magiclink/ "MD034": false, // [DONE] This option works in Node Markdownlint, not Ruby mdl: // [BUG] Temporary exclude rule before the new release: // https://github.com/mivok/markdownlint/pull/160 // "MD039": false, // In Pelican articles and pages first line — is Metadata, not header "MD041": false } ``` I use [**grunt-markdownlint**](https://github.com/sagiegurari/grunt-markdownlint) plugin. [**It supports JSON configuration file**](https://github.com/sagiegurari/grunt-markdownlint#usage): ``` example2: { options: { config: grunt.file.readJSON(rulesFile) //read linting rules from file } ``` `grunt.file.readJSON` doesn't support comments in `.markdownlintrc` file → I can't use comments in `.markdownlintrc`. [**Grunt support parsing YAML data**](https://gruntjs.com/api/grunt.file#grunt.file.readyaml). #### 2.2. Another reasons + [**JSON as configuration files: please don't**](https://arp242.net/weblog/json_as_configuration_files-_please_dont) Thanks.

kerem

2026-03-07 20:03:01 +03:00

closed this issue
added the
enhancement

fixed in next
labels

kerem commented

2026-03-07 20:03:02 +03:00

Author

Owner

@DavidAnson commented on GitHub (Apr 17, 2018):

Thanks for the detailed issue! There are JSON parsers that allow comments - would that work for you?

(JSON is already familiar to JavaScript programmers; I’m reluctant to introduce another file type that isn’t.)

@DavidAnson commented on GitHub (Apr 17, 2018): Thanks for the detailed issue! There are JSON parsers that allow comments - would that work for you? (JSON is already familiar to JavaScript programmers; I’m reluctant to introduce another file type that isn’t.)

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Apr 17, 2018):

(Unfortunately, changing the parser markdownlint uses won’t help with your Grunt scenario. I’ll think more about this.)

@DavidAnson commented on GitHub (Apr 17, 2018): (Unfortunately, changing the parser `markdownlint` uses won’t help with your Grunt scenario. I’ll think more about this.)

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Apr 17, 2018):

Wait - for your scenario, shouldn’t you be able to switch to a YAML file today and use grunt.file.readYAML to read it into a JavaScript object?

@DavidAnson commented on GitHub (Apr 17, 2018): Wait - for your scenario, shouldn’t you be able to switch to a YAML file today and use `grunt.file.readYAML` to read it into a JavaScript object?

kerem commented

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

Author

Owner

@Kristinita commented on GitHub (Apr 17, 2018):

@DavidAnson,

1. Grunt

✓ Works with YAML configuration file.

I convert JSON above to YAML file markdownlint.yml → I replace grunt.file.readJSON to grunt.file.readYAML in Gruntfile → grunt-markdownlint successful works.

I'm sorry, I didn't check it, because I didn't think it would work.

2. markdownlint-cli

☒ Doesn't support YAML configuration file.

markdownlint-cli (and Sublime Text Markdownlint, that needs markdownlint-cli).

3. Questions

How correctly to name Markdownlint YAML configuration file: markdownlint.yml or something else?
Maybe you add information about YAML configuration to Markdownlint documentation?

Thanks.

@Kristinita commented on GitHub (Apr 17, 2018): @DavidAnson, ### 1. Grunt ✓ Works with YAML configuration file. I convert JSON above to YAML file `markdownlint.yml` → I replace `grunt.file.readJSON` to `grunt.file.readYAML` in Gruntfile → grunt-markdownlint successful works. I'm sorry, I didn't check it, because I didn't think it would work. ### 2. markdownlint-cli ☒ Doesn't support YAML configuration file. [**markdownlint-cli**](https://github.com/igorshubovych/markdownlint-cli) (and [**Sublime Text Markdownlint**](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint), that needs markdownlint-cli). ### 3. Questions 1. How correctly to name Markdownlint YAML configuration file: `markdownlint.yml` or something else? 1. Maybe you add information about YAML configuration to Markdownlint documentation? Thanks.

kerem commented

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

Author

Owner

@DavidAnson commented on GitHub (Apr 17, 2018):

I would suggest .markdownlint.yaml. I think this may become a work item for the CLI project (where I would document it).

@DavidAnson commented on GitHub (Apr 17, 2018): I would suggest `.markdownlint.yaml`. I think this may become a work item for the CLI project (where I would document it).

kerem commented

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

Author

Owner

@Kristinita commented on GitHub (May 14, 2018):

@DavidAnson , we wait YAML configuration format for markdownlint-cli.

Thanks.

@Kristinita commented on GitHub (May 14, 2018): @DavidAnson , we wait YAML configuration format for markdownlint-cli. Thanks.

kerem referenced this issue

2026-03-07 20:09:32 +03:00

[GH-ISSUE #1947] MD010: make an exception for the content of code blocks. #2632

Rows
Columns

[GH-ISSUE #118] feature_request(configuration): support YAML configuration format #1947

1. Summary

2. Argumentation

2.1. Comments

2.2. Another reasons

1. Grunt

2. markdownlint-cli

3. Questions