Skip to content

Enchograph/VSCode-Markdownlint-Chinese-Localization

BranchesTags
 
 

Repository files navigation

Markdown 语法检查插件 / markdownlint Chinese Localization

适用于 Visual Studio Code 的 Markdown 或 CommonMark 语法与样式检查插件。

基于 David Anson 的 markdownlint 插件而开发。 The extention is based on the markdownlint of David Anson, which is its localization of Chinese.

具体规则

  • MD001 heading-increment - Heading levels should only increment by one level at a time

  • MD001 标题递增原则 - 标题层级应逐级递增。

  • MD003 heading-style - Heading style

  • MD003 标题格式 - 同一篇文档定义标题时应采用相同的语法

  • MD004 ul-style - Unordered list style

  • MD004 无序列表格式 - 无序列表格式

  • MD005 list-indent - Inconsistent indentation for list items at the same level

  • MD005 列表缩进 - 相同级别列表项具有不一致的缩进

  • MD007 ul-indent - Unordered list indentation

  • MD007 无序列表缩进 - 无序列表缩进

  • MD009 no-trailing-spaces - Trailing spaces

  • MD009 去除行末空格 - 行末有多余空格

  • MD010 no-hard-tabs - Hard tabs

  • MD010 去除硬制表符 - 存在硬制表符（ Tab 键所出）

  • MD011 no-reversed-links - Reversed link syntax

  • MD011 去除反向链接 - 存在反向链接（“ [] ”和“ () ”前后位置错误）

  • MD012 no-multiple-blanks - Multiple consecutive blank lines

  • MD012 去除重复空格 - 存在连续的重复空格

  • MD013 line-length - Line length

  • MD013 行长 - 控制每行最长长度

  • MD014 commands-show-output - Dollar signs used before commands without showing output

  • MD014 命令行控制语句 - 在不存在命令行命令对应输出时于其前显示“ $ ”符号。

  • MD018 no-missing-space-atx - No space after hash on atx style heading

  • MD018 井号后要加空格 - 井号后没有加空格

  • MD019 no-multiple-space-atx - Multiple spaces after hash on atx style heading

  • MD019 去除井号后多余空格 - 井号后有不止一个空格

  • MD020 no-missing-space-closed-atx - No space inside hashes on closed atx style heading

  • MD020 用于封闭标题的井号内要有空格 - 用于封闭标题的井号内没有空格

  • MD021 no-multiple-space-closed-atx - Multiple spaces inside hashes on closed atx style heading

  • MD021 去除用于封闭标题的井号内的多个空格 - 用于封闭标题的井号内有多个空格

  • MD022 blanks-around-headings - Headings should be surrounded by blank lines

  • MD022 标题应被空行包围 - 标题应被空行包围

  • MD023 heading-start-left - Headings must start at the beginning of the line

  • MD023 标题前不能有缩进 - 标题必须从行首开始。

  • MD024 no-duplicate-heading - Multiple headings with the same content

  • MD024 去除重复标题 - 存在多个内容相同的标题

  • MD025 single-title/single-h1 - Multiple top level headings in the same document

  • MD025 唯一标题原则 - 文档中存在多个顶级标题（ h1 ）

  • MD026 no-trailing-punctuation - Trailing punctuation in heading

  • MD026 标题以标点结尾 - 标题不应以标点结尾

  • MD027 no-multiple-space-blockquote - Multiple spaces after blockquote symbol

  • MD027 去除引用符号后的重复空格 - 引用符号后存在多个空格

  • MD028 no-blanks-blockquote - Blank line inside blockquote

  • MD028 引用块中不应存在空行 - 引用块中存在空行

  • MD029 ol-prefix - Ordered list item prefix

  • MD029 有序列表项前缀 - 有序列表项前缀格式不常见

  • MD030 list-marker-space - Spaces after list markers

  • MD030 列表标记后的空格 - 列表标记后的空格不符格式

  • MD031 blanks-around-fences - Fenced code blocks should be surrounded by blank lines

  • MD031 代码块周围应有空行 - 代码块应被空行包围

  • MD032 blanks-around-lists - Lists should be surrounded by blank lines

  • MD032 列表周围应有空行 - 列表应被空行包围

  • MD033 no-inline-html - Inline HTML

  • MD033 去除内联 HTML - 存在内联 HTML

  • MD034 去除裸链接 - 存在裸露的URL

  • MD034 no-bare-urls - Bare URL used

  • MD035 hr-style - Horizontal rule style

  • MD035 分割线样式 - 分割线应使用相同的样式

  • MD036 no-emphasis-as-heading - Emphasis used instead of a heading

  • MD036 不应使用加粗取代标题 - 对一整行使用了加粗，以此取代了标题

  • MD037 no-space-in-emphasis - Spaces inside emphasis markers

  • MD037 强调符应紧贴文字 - 强调符与文字间存在空格

  • MD038 no-space-in-code - Spaces inside code span elements

  • MD038 代码块内的空格 - 代码块内存在不合适的空格

  • MD039 no-space-in-links - Spaces inside link text

  • MD039 链接中不应有空格 - 中括号应紧贴超链接文本

  • MD040 fenced-code-language - Fenced code blocks should have a language specified

  • MD040 指定代码块语言 - 代码块应标识一种语言

  • MD041 first-line-heading/first-line-h1 - First line in file should be a top level heading

  • MD041 首行标题原则 - 文档的第一行应为顶级标题

  • MD042 no-empty-links - No empty links

  • MD042 不应有空链接 - 存在空链接

  • MD043 required-headings - Required heading structure

  • MD043 强制标题结构 - 与强制标题结构不符

  • MD044 proper-names - Proper names should have the correct capitalization

  • MD044 专有名称大小写 - 专有名称大小写应采用正确的大小写

  • MD045 no-alt-text - Images should have alternate text (alt text)

  • MD045 图片替代文本缺失 - 图片缺少替代文本

  • MD046 code-block-style - Code block style

  • MD046 代码块样式 - 代码块样式

  • MD047 single-trailing-newline - Files should end with a single newline character

  • MD047 文档末尾空行原则 - 文档应以空行结尾

  • MD048 code-fence-style - Code fence style

  • MD048 代码围栏样式 - 代码围栏样式

  • MD049 emphasis-style - Emphasis style should be consistent

  • MD049 斜体样式 - 全文斜体样式应一致

  • MD050 strong-style - Strong style should be consistent

  • MD050 粗体样式 - 全文粗体样式应一致

  • MD051 link-fragments - Link fragments should be valid

  • MD051 文内链接 - 与文章内部某处连接的链接应是合法的

  • MD052 reference-links-images - Reference links and images should use a label that is defined

  • MD052 链接与图片的引用 - 链接和图片应该使用标签进行引用，而非写出完整路径

  • MD053 link-image-reference-definitions - Link and image reference definitions should be needed

  • MD053 存在多余的标签 - 不应存在多余的标签

  • MD054 link-image-style - Link and image style

  • MD054 链接与图片样式 - 链接与图片样式

  • MD055 table-pipe-style - Table pipe style

  • MD055 表格分隔符样式 - 表格分隔符样式

  • MD056 table-column-count - Table column count

  • MD056 表格列数一致 - 表格列数应一致

  • MD058 blanks-around-tables - Tables should be surrounded by blank lines

  • MD058 表应该被空行包围 - 表应该被空行包围

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": true
}

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

Workspace

To lint all Markdown files in the current workspace, run the markdownlint.lintWorkspace command (from the Command Palette or by binding it to a keyboard shortcut). This will use markdownlint-cli2, the same engine that powers the extension, to lint all files and output the results to a new terminal in the "Terminal" panel. Results will also appear in the "Problems" panel (Ctrl+Shift+M/Ctrl+Shift+M/⇧⌘M) because of the problem matcher included with the extension. Entries in the "Problems" panel can be clicked to open the corresponding file in the editor. To customize the files that are included/excluded when linting a workspace, configure the markdownlint.lintWorkspaceGlobs setting (see below) at workspace or user scope.

Disable

To temporarily disable linting of Markdown documents, run the markdownlint.toggleLinting command (from the Command Palette or by binding it to a keyboard shortcut). To re-enable linting, run the markdownlint.toggleLinting command again.

Note: The effects of the markdownlint.toggleLinting command are reset when a new workspace is opened; linting defaults to enabled.

Configure

markdownlint.config

By default (i.e., without customizing anything), all rules are enabled except MD013/line-length because many files include lines longer than the conventional 80 character limit:

{
    "MD013": false
}

Rules can be enabled, disabled, and customized by creating a JSON file named .markdownlint.jsonc/.markdownlint.json or a YAML file named .markdownlint.yaml/.markdownlint.yml or a JavaScript file named .markdownlint.cjs in any directory of a project. Additionally, options (which include rules and things like markdown-it plugins and other settings) can be configured by creating a JSON file named .markdownlint-cli2.jsonc or a YAML file named .markdownlint-cli2.yaml or a JavaScript file named .markdownlint-cli2.cjs in any directory of a project.

For more information about configuration file precedence and complete examples, see the Configuration section of the markdownlint-cli2 README.md.

A custom configuration is often defined by a .markdownlint.json file in the root of the project:

{
    "default": true,
    "MD003": { "style": "atx_closed" },
    "MD007": { "indent": 4 },
    "no-hard-tabs": false
}

To extend another configuration file, such a file can use the extends property to provide a relative path:

{
    "extends": "../.markdownlint.json",
    "no-hard-tabs": true
}

Files referenced via extends do not need to be part of the current project (but usually are).

Rules can also be configured using VS Code's support for user and workspace settings.

The above configuration might look like the following in VS Code's user settings file:

{
    "editor.someSetting": true,
    "markdownlint.config": {
        "default": true,
        "MD003": { "style": "atx_closed" },
        "MD007": { "indent": 4 },
        "no-hard-tabs": false
    }
}

When using extends:

  • File paths referenced by extends from configuration files within a workspace are resolved relative to that configuration file.
  • When running VS Code locally:
    • File paths referenced by extends from user settings are resolved relative to the user's home directory (e.g., %USERPROFILE% on Windows or $HOME on macOS/Linux).
    • File paths referenced by extends from workspace settings are resolved relative to the workspace folder.
    • VS Code's predefined variables ${userHome} and ${workspaceFolder} can be used within an extends path from user or workspace settings to override the default behavior.

Configuration sources have the following precedence (in decreasing order):

  • .markdownlint-cli2.{jsonc,yaml,cjs} file in the same or parent directory
  • .markdownlint.{jsonc,json,yaml,yml,cjs} file in the same or parent directory
  • Visual Studio Code user/workspace settings
  • Default configuration (see above)

Configuration changes saved to any location take effect immediately. Files referenced via extends are not monitored for changes. Inherited configuration can be explicitly disabled (or re-enabled) in any configuration file.

When a workspace is open, running the markdownlint.openConfigFile command (from the Command Palette or by binding it to a keyboard shortcut) will open an editor for the .markdownlint-cli2.{jsonc,yaml,cjs} or .markdownlint.{jsonc,json,yaml,yml,cjs} configuration file in the root of the workspace. If none of these files exist, a new .markdownlint.json containing the default rule configuration will be opened in the editor in the "pending save" state.

Note: Because JavaScript is cached by VS Code after being loaded, edits to .markdownlint.cjs/.markdownlint-cli2.cjs require a restart of VS Code.

markdownlint.focusMode

By default, all linting issues are logged and highlighted as you type or edit a document. This includes "transient" issues like MD009/no-trailing-spaces such as when typing at the end of a line.

If you find this distracting, linting can be configured to ignore issues on the same line as the cursor. This looks like the following in VS Code's user settings:

{
    "editor.someSetting": true,
    "markdownlint.focusMode": true
}

To ignore issues on the N lines above and below the cursor, set focusMode to a positive integer representing the number of lines to ignore in each direction:

{
    "editor.someSetting": true,
    "markdownlint.focusMode": 2
}

The value of 2 in the example above will ignore issues on the line with the cursor, the 2 lines above it, and the 2 lines below it.

Note: This is an application-level setting and is only valid in user (not workspace) settings.

markdownlint.run

By default, linting is performed as you type or edit a document. Linting is fast and efficient and should not interfere with typical workflows.

If you find this distracting, linting can be configured to run only when the document is saved. This looks like the following in VS Code's user settings:

{
    "editor.someSetting": true,
    "markdownlint.run": "onSave"
}

Note: When configured to run onSave, the list of reported issues will become outdated while the document is edited and will update when the document is saved.

markdownlint.customRules

Custom rules can be specified in VS Code's user/workspace configuration to apply additional linting beyond the default set of rules. Custom rules are specified by the path to a JavaScript file or the name of or path to an npm package exporting one rule or an array of rules (examples of custom rules).

Paths are typically relative to the root of the current workspace and should begin with ./ to differentiate the relative path from a module identifier. Paths can be absolute and begin with /, though this is discouraged because it does not work reliably across different machines. If implementing custom rules in a workspace, consider committing the rule code under the .vscode directory where it will be separate from other workspace content and available to everyone who clones the repository. Paths of the form {extension}/path are relative to the base directory of the VS Code extension named extension (which must already be installed). This syntax allows custom rules to be included within another extension's package, though this is discouraged because it introduces a subtle dependency on the other extension.

An example of VS Code's workspace settings for custom rules might look like the following:

{
    "editor.someSetting": true,
    "markdownlint.customRules": [
        "./.vscode/my-custom-rule.js",
        "./.vscode/my-custom-rule-array.js",
        "./.vscode/npm-package-for-custom-rule",
        "/absolute/path/to/custom/rule.js",
        "{publisher.extension-name}/custom-rule.js",
        "{publisher.extension-name}/npm/rule/package"
    ]
}

For information about authoring custom rules, see the markdownlint documentation for custom rules.

Note: Custom rules can also be specified (in a portable way other tools will recognize) via the customRules property in .markdownlint-cli2.{jsonc,yaml,cjs}. In markdownlint-cli2 configuration files, the modulePaths property can be used in conjunction to specify one or more additional paths for resolving module references. This can be used to work around the VS Code limitation that globally-installed Node modules are unavailable by setting modulePaths to the location of the global module path (typically /usr/local/lib on macOS/Linux or ~/AppData/Roaming/npm on Windows).

markdownlint.lintWorkspaceGlobs

The globs used when linting a workspace with the markdownlint.lintWorkspace command match VS Code's concept of "Markdown files that matter":

[
    // Source: https://github.com/microsoft/vscode/blob/main/extensions/markdown-basics/package.json
    "**/*.{md,mkd,mdwn,mdown,markdown,markdn,mdtxt,mdtext,workbook}",
    // Source: https://github.com/microsoft/vscode/blob/main/src/vs/workbench/contrib/search/browser/search.contribution.ts
    "!**/*.code-search",
    "!**/bower_components",
    "!**/node_modules",
    // Additional exclusions
    "!**/.git",
    "!**/vendor"
]

This list can be customized at workspace and user scope to include or exclude additional files and directories. For more information about syntax, see the "Command Line" section of the markdownlint-cli2 documentation.

Suppress

Individual warnings can be suppressed with comments in the Markdown file itself:

<!-- markdownlint-disable MD037 -->
deliberate space * in * emphasis
<!-- markdownlint-enable MD037 -->

More information about inline suppressions can be found in the Configuration section of the markdownlint README.md.

Snippets

The following snippets are available when editing a Markdown document (press Ctrl+Space/Ctrl+Space/⌃Space for IntelliSense suggestions):

  • markdownlint-disable
  • markdownlint-enable
  • markdownlint-disable-line
  • markdownlint-disable-next-line
  • markdownlint-capture
  • markdownlint-restore
  • markdownlint-disable-file
  • markdownlint-enable-file
  • markdownlint-configure-file

Security

Running JavaScript from custom rules, markdown-it plugins, or configuration files (such as .markdownlint.cjs/.markdownlint-cli2.cjs) could be a security risk, so VS Code's Workspace Trust setting is honored to block JavaScript for untrusted workspaces.

History

See CHANGELOG.md.

markdownlint

Markdown/CommonMark linting and style checking for Visual Studio Code in Chinese

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

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": true
}

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

Workspace

To lint all Markdown files in the current workspace, run the markdownlint.lintWorkspace command (from the Command Palette or by binding it to a keyboard shortcut). This will use markdownlint-cli2, the same engine that powers the extension, to lint all files and output the results to a new terminal in the "Terminal" panel. Results will also appear in the "Problems" panel (Ctrl+Shift+M/Ctrl+Shift+M/⇧⌘M) because of the problem matcher included with the extension. Entries in the "Problems" panel can be clicked to open the corresponding file in the editor. To customize the files that are included/excluded when linting a workspace, configure the markdownlint.lintWorkspaceGlobs setting (see below) at workspace or user scope.

Disable

To temporarily disable linting of Markdown documents, run the markdownlint.toggleLinting command (from the Command Palette or by binding it to a keyboard shortcut). To re-enable linting, run the markdownlint.toggleLinting command again.

Note: The effects of the markdownlint.toggleLinting command are reset when a new workspace is opened; linting defaults to enabled.

Configure

markdownlint.config

By default (i.e., without customizing anything), all rules are enabled except MD013/line-length because many files include lines longer than the conventional 80 character limit:

{
    "MD013": false
}

Rules can be enabled, disabled, and customized by creating a JSON file named .markdownlint.jsonc/.markdownlint.json or a YAML file named .markdownlint.yaml/.markdownlint.yml or a JavaScript file named .markdownlint.cjs in any directory of a project. Additionally, options (which include rules and things like markdown-it plugins and other settings) can be configured by creating a JSON file named .markdownlint-cli2.jsonc or a YAML file named .markdownlint-cli2.yaml or a JavaScript file named .markdownlint-cli2.cjs in any directory of a project.

For more information about configuration file precedence and complete examples, see the Configuration section of the markdownlint-cli2 README.md.

A custom configuration is often defined by a .markdownlint.json file in the root of the project:

{
    "default": true,
    "MD003": { "style": "atx_closed" },
    "MD007": { "indent": 4 },
    "no-hard-tabs": false
}

To extend another configuration file, such a file can use the extends property to provide a relative path:

{
    "extends": "../.markdownlint.json",
    "no-hard-tabs": true
}

Files referenced via extends do not need to be part of the current project (but usually are).

Rules can also be configured using VS Code's support for user and workspace settings.

The above configuration might look like the following in VS Code's user settings file:

{
    "editor.someSetting": true,
    "markdownlint.config": {
        "default": true,
        "MD003": { "style": "atx_closed" },
        "MD007": { "indent": 4 },
        "no-hard-tabs": false
    }
}

When using extends:

  • File paths referenced by extends from configuration files within a workspace are resolved relative to that configuration file.
  • When running VS Code locally:
    • File paths referenced by extends from user settings are resolved relative to the user's home directory (e.g., %USERPROFILE% on Windows or $HOME on macOS/Linux).
    • File paths referenced by extends from workspace settings are resolved relative to the workspace folder.
    • VS Code's predefined variables ${userHome} and ${workspaceFolder} can be used within an extends path from user or workspace settings to override the default behavior.

Configuration sources have the following precedence (in decreasing order):

  • .markdownlint-cli2.{jsonc,yaml,cjs} file in the same or parent directory
  • .markdownlint.{jsonc,json,yaml,yml,cjs} file in the same or parent directory
  • Visual Studio Code user/workspace settings
  • Default configuration (see above)

Configuration changes saved to any location take effect immediately. Files referenced via extends are not monitored for changes. Inherited configuration can be explicitly disabled (or re-enabled) in any configuration file.

When a workspace is open, running the markdownlint.openConfigFile command (from the Command Palette or by binding it to a keyboard shortcut) will open an editor for the .markdownlint-cli2.{jsonc,yaml,cjs} or .markdownlint.{jsonc,json,yaml,yml,cjs} configuration file in the root of the workspace. If none of these files exist, a new .markdownlint.json containing the default rule configuration will be opened in the editor in the "pending save" state.

Note: Because JavaScript is cached by VS Code after being loaded, edits to .markdownlint.cjs/.markdownlint-cli2.cjs require a restart of VS Code.

markdownlint.focusMode

By default, all linting issues are logged and highlighted as you type or edit a document. This includes "transient" issues like MD009/no-trailing-spaces such as when typing at the end of a line.

If you find this distracting, linting can be configured to ignore issues on the same line as the cursor. This looks like the following in VS Code's user settings:

{
    "editor.someSetting": true,
    "markdownlint.focusMode": true
}

To ignore issues on the N lines above and below the cursor, set focusMode to a positive integer representing the number of lines to ignore in each direction:

{
    "editor.someSetting": true,
    "markdownlint.focusMode": 2
}

The value of 2 in the example above will ignore issues on the line with the cursor, the 2 lines above it, and the 2 lines below it.

Note: This is an application-level setting and is only valid in user (not workspace) settings.

markdownlint.run

By default, linting is performed as you type or edit a document. Linting is fast and efficient and should not interfere with typical workflows.

If you find this distracting, linting can be configured to run only when the document is saved. This looks like the following in VS Code's user settings:

{
    "editor.someSetting": true,
    "markdownlint.run": "onSave"
}

Note: When configured to run onSave, the list of reported issues will become outdated while the document is edited and will update when the document is saved.

markdownlint.customRules

Custom rules can be specified in VS Code's user/workspace configuration to apply additional linting beyond the default set of rules. Custom rules are specified by the path to a JavaScript file or the name of or path to an npm package exporting one rule or an array of rules (examples of custom rules).

Paths are typically relative to the root of the current workspace and should begin with ./ to differentiate the relative path from a module identifier. Paths can be absolute and begin with /, though this is discouraged because it does not work reliably across different machines. If implementing custom rules in a workspace, consider committing the rule code under the .vscode directory where it will be separate from other workspace content and available to everyone who clones the repository. Paths of the form {extension}/path are relative to the base directory of the VS Code extension named extension (which must already be installed). This syntax allows custom rules to be included within another extension's package, though this is discouraged because it introduces a subtle dependency on the other extension.

An example of VS Code's workspace settings for custom rules might look like the following:

{
    "editor.someSetting": true,
    "markdownlint.customRules": [
        "./.vscode/my-custom-rule.js",
        "./.vscode/my-custom-rule-array.js",
        "./.vscode/npm-package-for-custom-rule",
        "/absolute/path/to/custom/rule.js",
        "{publisher.extension-name}/custom-rule.js",
        "{publisher.extension-name}/npm/rule/package"
    ]
}

For information about authoring custom rules, see the markdownlint documentation for custom rules.

Note: Custom rules can also be specified (in a portable way other tools will recognize) via the customRules property in .markdownlint-cli2.{jsonc,yaml,cjs}. In markdownlint-cli2 configuration files, the modulePaths property can be used in conjunction to specify one or more additional paths for resolving module references. This can be used to work around the VS Code limitation that globally-installed Node modules are unavailable by setting modulePaths to the location of the global module path (typically /usr/local/lib on macOS/Linux or ~/AppData/Roaming/npm on Windows).

markdownlint.lintWorkspaceGlobs

The globs used when linting a workspace with the markdownlint.lintWorkspace command match VS Code's concept of "Markdown files that matter":

[
    // Source: https://github.com/microsoft/vscode/blob/main/extensions/markdown-basics/package.json
    "**/*.{md,mkd,mdwn,mdown,markdown,markdn,mdtxt,mdtext,workbook}",
    // Source: https://github.com/microsoft/vscode/blob/main/src/vs/workbench/contrib/search/browser/search.contribution.ts
    "!**/*.code-search",
    "!**/bower_components",
    "!**/node_modules",
    // Additional exclusions
    "!**/.git",
    "!**/vendor"
]

This list can be customized at workspace and user scope to include or exclude additional files and directories. For more information about syntax, see the "Command Line" section of the markdownlint-cli2 documentation.

Suppress

Individual warnings can be suppressed with comments in the Markdown file itself:

<!-- markdownlint-disable MD037 -->
deliberate space * in * emphasis
<!-- markdownlint-enable MD037 -->

More information about inline suppressions can be found in the Configuration section of the markdownlint README.md.

Snippets

The following snippets are available when editing a Markdown document (press Ctrl+Space/Ctrl+Space/⌃Space for IntelliSense suggestions):

  • markdownlint-disable
  • markdownlint-enable
  • markdownlint-disable-line
  • markdownlint-disable-next-line
  • markdownlint-capture
  • markdownlint-restore
  • markdownlint-disable-file
  • markdownlint-enable-file
  • markdownlint-configure-file

Security

Running JavaScript from custom rules, markdown-it plugins, or configuration files (such as .markdownlint.cjs/.markdownlint-cli2.cjs) could be a security risk, so VS Code's Workspace Trust setting is honored to block JavaScript for untrusted workspaces.

History

See CHANGELOG.md.

About

VS Code Markdown 语法检查插件汉化

marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages

  • JavaScript 100.0%