markdownlint-cli2-formatter-template

> An output formatter for [markdownlint-cli2][markdownlint-cli2] that displays
> results using a template

[![npm version][npm-image]][npm-url]
[![License][license-image]][license-url]

Install

``bash
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][workflow-commands],
use something like the following .markdownlint-cli2.jsonc:

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

Which produces output like:

`text
::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][task-logissue],
use something like the following .markdownlint-cli2.jsonc:

`json
{
"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:

`text
##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
``

[license-image]: https://img.shields.io/npm/l/markdownlint-cli2-formatter-template.svg
[license-url]: https://opensource.org/licenses/MIT
[markdownlint-cli2]: https://github.com/DavidAnson/markdownlint-cli2
[npm-image]: https://img.shields.io/npm/v/markdownlint-cli2-formatter-template.svg
[npm-url]: https://www.npmjs.com/package/markdownlint-cli2-formatter-template
[task-logissue]: https://learn.microsoft.com/en-us/azure/devops/pipelines/scripts/logging-commands?view=azure-devops&tabs=bash#logissue-log-an-error-or-warning
[workflow-commands]: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions