markdownlint-cli2-formatter-template

An output formatter for markdownlint-cli2 that displays results using a template.

Install

npm install markdownlint-cli2-formatter-template --save-dev

Use

This output formatter makes it easy to custom-format linting violations. To specify an output format, set the template parameter to a string with text and one or more tokens representing any of the following elements. The specified template will be applied once for each violation.

These tokens are always defined:

| Token | Meaning | |-------------------|-----------------------| | fileName | File name | | lineNumber | Line number (1-based) | | ruleName | Rule name (full) | | ruleDescription | Rule description | | ruleInformation | Informational URL |

These tokens are sometimes defined (depending on the rule/violation):

| Token | Meaning | |----------------|-------------------------| | columnNumber | Column number (1-based) | | errorContext | Context information | | errorDetail | Additional detail |

In the simplest case, tokens are specified with the syntax ${token}. This is all that's needed for tokens that are always defined. To support scenarios where a token may not be defined, the syntaxes ${token:text if present} and ${token!text if not present} are also supported. This allows for templates to accommodate missing data. Only one level of token nesting is supported.

A few examples demonstrate the concept:

| Template | Output if defined | Output if not defined | |--------------------------------------------------------------------------|-------------------|-----------------------| | Column=${columnNumber} | Column=10 | Column= | | ${columnNumber:Column=${columnNumber}} | Column=10 | | | ${columnNumber!No column number} | | No column number | | ${columnNumber:Column=${columnNumber}}${columnNumber!No column number} | Column=10 | No column number |

Example

To output in the Azure Pipelines Task command LogIssue format, use something like the following .markdownlint-cli2.jsonc:

{
  "outputFormatters": [
    [
      "markdownlint-cli2-formatter-template",
      {
        "template": "##vso[task.logissue type=error;sourcepath=${fileName};linenumber=${lineNumber};${columnNumber:columnumber=${columnNumber};}code=${ruleName}]${ruleDescription}"
      }
    ]
  ]
}

Which produces output like:

##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=3;columnumber=10;code=MD009/no-trailing-spaces]Trailing spaces
##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=5;code=MD012/no-multiple-blanks]Multiple consecutive blank lines
##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=6;code=MD025/single-title/single-h1]Multiple top-level headings in the same document
##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=12;columnumber=4;code=MD019/no-multiple-space-atx]Multiple spaces after hash on atx style heading
##vso[task.logissue type=error;sourcepath=viewme.md;linenumber=14;columnumber=14;code=MD047/single-trailing-newline]Files should end with a single newline character