Add GitHub formatter

[mschoettle]

I so far have used the sarif formatter and used the upload-sarif action to upload the results.

I came across another format which makes GitHub add check annotations (see: https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/workflow-commands-for-github-actions#setting-an-error-message). For example, the ruff linter has support for this output format: https://docs.astral.sh/ruff/settings/#output-format

I think this would be more appropriate for markdownlint and also does not require the security-events: write permission.

Would you be open to including a github formatter?

[DavidAnson]

My first question is why not use the existing GitHub Action which already outputs annotations: https://github.com/DavidAnson/markdownlint-cli2-action

My second comment is that this scenario seemed very familiar and I was about to have the same conversation but now we can short circuit that: #426

Specifically, I expect you should be able to create a template for the GitHub format just like I have done for Azure and can use the existing template formatter: https://github.com/DavidAnson/markdownlint-cli2/tree/main/formatter-template

If you do, I would be happy to take a PR that adds that format to the documentation like I did for the Azure example.

[mschoettle]

My first question is why not use the existing GitHub Action which already outputs annotations: https://github.com/DavidAnson/markdownlint-cli2-action

It's because I have some projects that use an extra rule. It's contained in the rules image of markdownlint-cli2 which unfortunately does not work with the action as far as I understand.

Thanks for the pointer. I will give the template formatter a try. Happy to create a PR once I figure it out.

[DavidAnson]

It's contained in the rules image of markdownlint-cli2 which unfortunately does not work with the action as far as I understand.

It should be OK if you reference that extra rule as one of the dependencies of your project that get installed before running the action, but you're right that the action doesn't bundle the set of extra rules in the Docker container image.

[mschoettle]

I just saw that you added an example to the documentation with a template. Thanks a lot!

I wanted to try it out but am having trouble configuring two formatters with the YAML config.

What I had before was:

outputFormatters:
  - - markdownlint-cli2-formatter-pretty
  - - markdownlint-cli2-formatter-sarif

Now I want to replace the SARIF formatter with the template formatter and define the template but somehow with the format that I had this does not work.

What's the correct way to define this in YAML when there is more than one formatter?

[DavidAnson]

Boop converts the sample from https://github.com/DavidAnson/markdownlint-cli2/blob/50e1be2d6f205fdc2f2aca1f786c882e9fce5aac/formatter-template/README.md to this:

outputFormatters:
  - - markdownlint-cli2-formatter-template
    - template: >-
        ::error
        file=${fileName},line=${lineNumber},${columnNumber:col=${columnNumber},}title=${ruleName}::${ruleDescription}

It looks like the template value can alternatively be expressed on a single line without folded chomping syntax:

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

[mschoettle]

That works, thanks a lot!

[DavidAnson]

markdownlint-cli2-formatter-template@0.0.3