markdownlint-cli2-formatter-template

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
errorSeverity	Severity (error/warning)

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

Examples

To output in the GitHub Actions workflow commands format, use something like the following .markdownlint-cli2.jsonc:

{
  "outputFormatters": [
    [
      "markdownlint-cli2-formatter-template",
      {
        "template": "::${errorSeverity:${errorSeverity}}${errorSeverity!error} file=${fileName},line=${lineNumber},${columnNumber:col=${columnNumber},}title=${ruleName}::${ruleDescription}"
      }
    ]
  ]
}

Which produces output like:

::error file=viewme.md,line=3,col=10,title=MD009/no-trailing-spaces::Trailing spaces
::warning file=viewme.md,line=5,title=MD012/no-multiple-blanks::Multiple consecutive blank lines
::error file=viewme.md,line=6,title=MD025/single-title/single-h1::Multiple top-level headings in the same document
::error file=viewme.md,line=12,col=4,title=MD019/no-multiple-space-atx::Multiple spaces after hash on atx style heading
::warning file=viewme.md,line=14,col=14,title=MD047/single-trailing-newline::Files should end with a single newline character

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=${errorSeverity:${errorSeverity}}${errorSeverity!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=warning;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=warning;sourcepath=viewme.md;linenumber=14;columnumber=14;code=MD047/single-trailing-newline]Files should end with a single newline character