An output formatter for markdownlint-cli2 that displays results using a template
npm install 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]
``bash`
npm install markdownlint-cli2-formatter-template --save-dev
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${token:text if present}
all that's needed for tokens that are always defined. To support scenarios where
a token may not be defined, the syntaxes 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 |
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