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