lint: consider scope of markdown linting in configlet

[ee7]

Follow-up on some discussions with Erik, starting from implementation options for #328.

I suggested that for a first implementation of markdown linting, we could consider adding markdownlint as an org-wide workflow (rather than adding it to configlet lint).

The downside: running configlet lint locally runs a smaller subset of checks that occur in CI. But configlet lint is not supposed to be the only CI check for every track, and even for configlet lint JSON checking we might add CI-only checks anyway (e.g. for Exercise-wide checks - see #178).

---

@ee7 wrote:

There is some question about how to separate things. For a simpler example, it's probably nice to have org-wide whitespace checking. So should configlet lint do that, or an org-wide workflow?

There we might argue that:

1. The scope of configlet lint is track repos
2. Exercism has more than just track repos
3. Other repos might have whitespace problems
4. Therefore whitespace checking should be done outside of configlet lint

Regarding the markdownlint option, I guess it depends on how many rules we have that markdownlint cannot catch. That is, things that are valid markdown, but violate some Exercism-specific linting rule.

By the same reasoning, it makes sense to have the JSON linting in configlet lint (as we have already), because:

1. The scope of configlet lint is track repos
2. Only track repos have certain JSON files
3. Parsing JSON (and confirming that it's valid) is easy
4. We're checking lots of Exercism-specific rules that are not about JSON validity, and are even difficult/impossible to express in e.g. JSON schema
5. With those files, it's more useful to have fast local linting without installing dependencies (which configlet provides)

But if we want lots of the checks that markdownlint provides, it's probably a significant amount of work to essentially reimplement markdownlint in pure Nim

[ee7]

Otherwise, the main available Markdown libraries seem to be:

• https://github.com/soasme/nim-markdown
• https://github.com/zengxs/nim-cmark (which wraps https://github.com/commonmark/cmark)

I haven't used either. It is also possible to wrap some other C library.

[ErikSchierboom]

nim-cmark requires that libcmark is installed and the shared library is available.

That does mean that we would be adding an extra prerequisite, right?

Having slept on it a bit, I think having a GitHub action for Markdown linting might be a more sane option. There are several benefits to it:

• It is easy to implement, as it doesn't require us to re-implement all the Markdown linting rules
• It is easy to integrate (see https://github.com/exercism/rust/blob/858a6a7cb3774ebf35c762bcf138f3d3ad4455fc/.github/workflows/tests.yml#L66)
• It could work well with an additional GHA workflow that would allow formatting via a comment

The downsides are:

• Maintainers might have to do work even though configlet tells them everything is fine
• We don't integrate with configlet fmt

A hybrid approach would be to have an API method that configlet could call to format Markdown, but that seems quite wasteful.

[ee7]

That does mean that we would be adding an extra prerequisite, right?

We might be able to link it statically.

I think having a GitHub action for Markdown linting might be a more sane option.

To others: note that the configlet repo has markdownlint in CI:

• https://github.com/exercism/configlet/blob/main/.github/workflows/markdownlint.yml
• https://github.com/exercism/configlet/blob/main/.markdownlint.jsonc