markdownlint

Markdown/CommonMark linting and style checking for Visual Studio Code

Introduction

The Markdown markup language is designed to be easy to read, write, and understand. It succeeds - and its flexibility is both a benefit and a drawback. Many styles are possible, so formatting can be inconsistent. Some constructs don't work well in all parsers and should be avoided. For example, here are some common/troublesome Markdown constructs.

markdownlint is an extension for the Visual Studio Code editor that includes a library of rules to encourage standards and consistency for Markdown files. It is powered by the markdownlint library for Node.js (which was inspired by markdownlint for Ruby). Linting is performed by the markdownlint-cli2 engine, which can be used in conjunction with this extension to provide command-line support for scripts and continuous integration scenarios. The markdownlint-cli2-action GitHub Action uses the same engine and can be integrated with project workflows.

Install

1. Open Visual Studio Code
2. Press Ctrl+P/Ctrl+P/⌘P to open the Quick Open dialog
3. Type ext install markdownlint to find the extension
4. Click the Install button, then the Enable button

OR

1. Press Ctrl+Shift+X/Ctrl+Shift+X/⇧⌘X to open the Extensions tab
2. Type markdownlint to find the extension
3. Click the Install button, then the Enable button

OR

1. Open a command-line prompt
2. Run code --install-extension DavidAnson.vscode-markdownlint

Use

When editing a Markdown file in VS Code with markdownlint installed, any lines that violate one of markdownlint's rules (see below) will trigger a Warning in the editor. Warnings are indicated by a wavy green underline and can also be seen by pressing Ctrl+Shift+M/Ctrl+Shift+M/⇧⌘M to open the Errors and Warnings dialog. Hover the mouse pointer over a green line to see the warning or press F8 and Shift+F8/Shift+F8/⇧F8 to cycle through all the warnings (markdownlint warnings all begin with MD###). For more information about a markdownlint warning, place the cursor on a line and click the light bulb icon or press Ctrl+./Ctrl+./⌘. to open the quick fix dialog. Clicking one of the warnings in the dialog will display that rule's help entry in the default web browser.

For a tutorial, please see Build an Amazing Markdown Editor Using Visual Studio Code and Pandoc by Dave Johnson.

By default, markdownlint will scan and report issues for files that VS Code treats as Markdown. You can see what language mode the current file has in the Status Bar at the bottom of the window and you can change the language mode for the current file. If you have a custom file type that VS Code should always treat as Markdown, you can associate that file extension with the markdown language identifier.

Rules

• MD001 heading-increment - Heading levels should only increment by one level at a time
• MD003 heading-style - Heading style
• MD004 ul-style - Unordered list style
• MD005 list-indent - Inconsistent indentation for list items at the same level
• MD007 ul-indent - Unordered list indentation
• MD009 no-trailing-spaces - Trailing spaces
• MD010 no-hard-tabs - Hard tabs
• MD011 no-reversed-links - Reversed link syntax
• MD012 no-multiple-blanks - Multiple consecutive blank lines
• MD013 line-length - Line length
• MD014 commands-show-output - Dollar signs used before commands without showing output
• MD018 no-missing-space-atx - No space after hash on atx style heading
• MD019 no-multiple-space-atx - Multiple spaces after hash on atx style heading
• MD020 no-missing-space-closed-atx - No space inside hashes on closed atx style heading
• MD021 no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading
• MD022 blanks-around-headings - Headings should be surrounded by blank lines
• MD023 heading-start-left - Headings must start at the beginning of the line
• MD024 no-duplicate-heading - Multiple headings with the same content
• MD025 single-title/single-h1 - Multiple top level headings in the same document
• MD026 no-trailing-punctuation - Trailing punctuation in heading
• MD027 no-multiple-space-blockquote - Multiple spaces after blockquote symbol
• MD028 no-blanks-blockquote - Blank line inside blockquote
• MD029 ol-prefix - Ordered list item prefix
• MD030 list-marker-space - Spaces after list markers
• MD031 blanks-around-fences - Fenced code blocks should be surrounded by blank lines
• MD032 blanks-around-lists - Lists should be surrounded by blank lines
• MD033 no-inline-html - Inline HTML
• MD034 no-bare-urls - Bare URL used
• MD035 hr-style - Horizontal rule style
• MD036 no-emphasis-as-heading - Emphasis used instead of a heading
• MD037 no-space-in-emphasis - Spaces inside emphasis markers
• MD038 no-space-in-code - Spaces inside code span elements
• MD039 no-space-in-links - Spaces inside link text
• MD040 fenced-code-language - Fenced code blocks should have a language specified
• MD041 first-line-heading/first-line-h1 - First line in file should be a top level heading
• MD042 no-empty-links - No empty links
• MD043 required-headings - Required heading structure
• MD044 proper-names - Proper names should have the correct capitalization
• MD045 no-alt-text - Images should have alternate text (alt text)
• MD046 code-block-style - Code block style
• MD047 single-trailing-newline - Files should end with a single newline character
• MD048 code-fence-style - Code fence style
• MD049 emphasis-style - Emphasis style should be consistent
• MD050 strong-style - Strong style should be consistent
• MD051 link-fragments - Link fragments should be valid
• MD052 reference-links-images - Reference links and images should use a label that is defined
• MD053 link-image-reference-definitions - Link and image reference definitions should be needed
• MD054 link-image-style - Link and image style
• MD055 table-pipe-style - Table pipe style
• MD056 table-column-count - Table column count
• MD058 blanks-around-tables - Tables should be surrounded by blank lines
• MD059 descriptive-link-text - Link text should be descriptive
• MD060 table-column-style - Table column style

See markdownlint's Rules.md file for more details.

The following rules can be automatically fixed by moving the cursor to a rule violation (wavy underlined text) and typing Ctrl+./Ctrl+./⌘. or clicking the light bulb icon.

• MD004 ul-style
• MD005 list-indent
• MD007 ul-indent
• MD009 no-trailing-spaces
• MD010 no-hard-tabs
• MD011 no-reversed-links
• MD012 no-multiple-blanks
• MD014 commands-show-output
• MD018 no-missing-space-atx
• MD019 no-multiple-space-atx
• MD020 no-missing-space-closed-atx
• MD021 no-multiple-space-closed-atx
• MD022 blanks-around-headings
• MD023 heading-start-left
• MD026 no-trailing-punctuation
• MD027 no-multiple-space-blockquote
• MD030 list-marker-space
• MD031 blanks-around-fences
• MD032 blanks-around-lists
• MD034 no-bare-urls
• MD037 no-space-in-emphasis
• MD038 no-space-in-code
• MD039 no-space-in-links
• MD044 proper-names
• MD047 single-trailing-newline
• MD049 emphasis-style
• MD050 strong-style
• MD051 link-fragments
• MD053 link-image-reference-definitions
• MD054 link-image-style
• MD058 blanks-around-tables

Commands

Fix

All of a document's violations of the automatically-fixable rules above can be fixed for you.

markdownlint registers itself as a source code formatter for Markdown files and can be invoked by the Format Document/editor.action.formatDocument and Format Selection/editor.action.formatSelection commands, either from the Command Palette (via View|Command Palette... or Ctrl+Shift+P/Ctrl+Shift+P/⇧⌘P) or via the default key bindings of Shift+Alt+F/Ctrl+Shift+I/⇧⌥F (to format the document) and Ctrl+K Ctrl+F/Ctrl+K Ctrl+F/⌘K ⌘F (to format the selection). To automatically format when saving or pasting into a Markdown document, configure Visual Studio Code's editor.formatOnSave or editor.formatOnPaste settings like so:

"[markdown]": {
    "editor.formatOnSave": true,
    "editor.formatOnPaste": true
},

markdownlint also contributes the markdownlint.fixAll command which fixes a document's violations in one step and can be run from the Command Palette or by binding the command to a keyboard shortcut. To automatically fix violations when saving a Markdown document, configure Visual Studio Code's editor.codeActionsOnSave setting like so:

"editor.codeActionsOnSave": {
    "source.fixAll.markdownlint": "explicit"
}

Automatically-applied fixes from either method can be reverted by Edit|Undo or Ctrl+Z/Ctrl+Z/