Linting possibilities

[petemounce]

Do you have any recommendations for linting setup?

I'm using markdownlint inside my vscode, and it balks at things like admonitions in lists.

I've only just recently started to use mkdocs-material, so I don't have a lot of examples of other fiddly bits, nor have I started looking into this "for reals" yet; this post is really the beginnings of research.

We're using mkdocs-material for handbook-first docs-as-code - and may I say it has been an altogether pleasant experience so far, extremely batteries-included and Just Works ™️. Since I launched it, contributions to docs have increased dramatically!

I need to support both developers who have a local iteration loop, and not-developers who edit via github exclusively. Both need to readily understand CI/local feedback.

My ideal end result includes:

• understands the markdown extensions in play via mkdocs, python-markdown (which I now realise isn't CommonMark), material
• minimal configuration to linter to include/exclude rules inline; I don't want my authors dealing with inline comment gunk in content files.
• ideally python ecosystem to avoid ecosystem sprawl and dependency management. That said, we're a bazel shop, so that's not fatal; just undesirable.
• has a pre-commit.com plugin
• highlights errors by file, line, character
• has a github action or single static binary to install
• can work on GitHub.dev editor (and I want a pony!) (Speaking of, can edit_uri aim at that...?)

[facelessuser]

I'm using markdownlint inside my vscode, and it balks at things like admonitions in lists.

Unfortunately, any plugins beyond that extend Markdown, even in CommonMark, could give a Markdown linter trouble as the syntax might be non-standard. With that said, the admonition issues do seem to be a fairly unique issue to Python Markdown.

Admonitions were shipped as an official solution included with the official Python Markdown. It used the BlockProcessor which expects a single block, but admonitons are more like a container that can hold multiple blocks, kind of like lists. They were done with the same indented style as lists as it was easiest to implement them as such. But it seems that other parsers have generally implemented such constructs in different ways making Python Markdown's solution fairly unique.

So, now we have multiple extensions that have piggy backed off this idea: pymdownx.details, pymdownx.tabbed, etc. This has not only causes issues for linters, but code syntax highlighting in editors as well. Indented blocks are expected to be code blocks in most highlighters and linters, and there is no special considerations for special headers that define indented list-like content.

Moving forward, I've actually been spending time creating a new generic block format inspired by RST directives. Currently, they are functional and will allow for creating custom blocks like admonitions without indentation: facelessuser/pymdown-extensions#1777.

It is difficult coming up with brand new, non-conflicting syntax every time a new plugin wants to create some sort of new block or container, so we are hoping that a new generic block will make this much easier and eliminate the indentation problems that are present in existing containers that employ indentation.

I believe linked solution for generic blocks is getting very close to completion, I just need to find the time to finish polishing it up and testing all the corner cases.

I do not currently have a recommendation for a minimal linting recommendation as I do not currently employ Markdown linting in my projects, but maybe someone else has some good suggestions.

[petemounce]

Thanks very much for your considered response!

[rehevkor5]

Vale is another good example of a tool that understands Markdown, and therefore interprets mkdocs adminitions as code blocks due to the indentation.

It looks like your approach is usable via your extension? https://facelessuser.github.io/pymdown-extensions/extensions/blocks/plugins/admonition/

[facelessuser]

Yes, that is the fenced approach. Using the new fenced approach allows me to limit the need for crazy new syntax to implement new blocks and reduce how much nested indentation is needed.