Skip to content

Latest commit

 

History

History
125 lines (91 loc) · 4.9 KB

configuration.md

File metadata and controls

125 lines (91 loc) · 4.9 KB
Raw

Mdl configuration

Markdownlint has several options you can configure both on the command line, or in markdownlint's configuration file: .mdlrc, first looked for in the working directory, then in your home directory. While markdownlint will work perfectly well out of the box, this page documents some of the options you can change to suit your needs.

In general, anything you pass on the command line can also be put into ~/.mdlrc with the same option. For example, if you pass --style foo on the command line, you can make this the default by putting style "foo" into your ~/.mdlrc file.

Configuration options

General options

Verbose - Print additional information about what markdownlint is doing.

  • Command line: -v, --verbose
  • Config file: verbose true
  • Default: false

Show warnings - Kramdown will generate warnings of its own for some issues found with documents during parsing, and markdownlint can print these out in addition to using the built in rules. This option enables/disables that behavior.

  • Command line: -w, --warnings
  • Config file: show_kramdown_warnings true
  • Default: true

Recurse using files known to git - When mdl is given a directory name on the command line, it will recurse into that directory looking for markdown files to process. If this option is enabled, it will use git to look for files instead, and ignore any files git doesn't know about.

  • Command line: -g, --git-recurse
  • Config file: git_recurse true
  • Default: false

Ignore YAML front matter - If this option is enabled markdownlint will ignore content within valid YAML front matter. Reported line numbers will still match the file contents but markdownlint will consider the line following front matter to be the first line.

  • Command line: -i, --ignore-front-matter
  • Config file: ignore_front_matter true
  • Default: false

Specifying which rules mdl processes

Tags - Limit the rules mdl enables to those containing the provided tags.

  • Command line: -t tag1,tag2, --tags tag1,tag2, -t ~tag1,~tag2
  • Config file: tags "tag1", "tag2"
  • Default: process all rules (no tag limit)

Rules - Limit the rules mdl enables to those provided in this option.

  • Command line: -r MD001,MD002, --rules MD001,MD002, -r ~MD001,~MD002
  • Config file: rules "MD001", "MD002"
  • Default: process all rules (no rule limit)

If a rule or tag ID is preceded by a tilde (~), then it disables the matching rules instead of enabling them, starting with all rules being enabled.

Note: If both --rules and --tags are provided, then a given rule has to both be in the list of enabled rules, as well as be tagged with one of the tags provided with the --tags option. Use the -l/--list-rules option to test this behavior.

Style - Select which style mdl uses. A 'style' is a file containing a list of enabled/disable rules, as well as options for some rules that take them. For example, one style might enforce a line length of 80 characters, while another might choose 72 characters, and another might have no line length limit at all (rule MD013).

  • Command line: -s style_name, --style style_name
  • Config file: style "style_name"
  • Default: Use the style called 'default'

Note: The value for style_name must either end with .rb or have / in it in order to tell mdl to look for a custom style, and not a built-in style.

Note: When setting style in mdlrc, it is highly recommended that either a fully-qualified path be used, or that the relative values be passed in a form like File.join(File.dirname(__FILE__), '.mdl.style') so that the value is relative to the mdlrc and not the path the user happens to be in.

Rulesets - Load a custom ruleset file. This option allows you to load custom rules in addition to those included with markdownlint.

  • Command line: -u ruleset.rb,ruleset2.rb, --rulesets ruleset.rb,ruleset2.rb
  • Config file: rulesets ['ruleset.rb', 'ruleset2.rb']
  • Default: Don't load any additional rulesets

No default ruleset - Skip loading the default ruleset file included with markdownlint. Use this option if you only want to load custom rulesets.

  • Command line: -d, --skip-default-ruleset
  • Config file: skip_default_ruleset true
  • Default: Load the default ruleset.

Creating your own .mdlrc files

You can configure mdl using your own .mdlrc file. You can specify and command-line option in this file.

In particular you can specify a style file, where you have configured any rules. Here's a simple example that just points to a style file:

style "#{File.dirname(__FILE__)}/{your_markdown_rule_file_path}.rb"

As commented, this path is relative to .mdlrc file. You can find a basic example of .mdlrc file here.

Then you should create your new rule or style.

You can find a basic example of new style file here.