Feature request: exclude/ignore option

[jspaezp]

Context

Hello!

I would love to use it as mdformat . (like black) and have it ignore all files I know should be ignored and include any that should be included but is not explicitly formatted with .md extension.

I understand that the current suggested usage as a pre-commit hook uses their exclusion argument to exclude files. But i feel like having it in the cli would be great.

Let me know what you think.

Proposal

I would like to propose adding exclude and include options to the cli (and by extension the configuration toml). I believe it would be great for its usage in the command line.

Tasks and updates

No response

[juhannc]

YES! This is especially important for custom keywords/macros.

GitLab Flavored Markdown for example has a dynamic table of content. It can be added by putting the macro [TOC] or [[_TOC_]] into the code. But mdformat always replaces it with either \[TOC\] or \[\[_TOC\]\].

[jspaezp]

@juhannc I think we are talking about slightly different things. I was thinking more of a "ignore these files in the path", i feel like you are talking about "ignoring sections containing xxx content" right? (i think the later can be achieved with a plugin).

[juhannc]

Ah yes, I see, my bad.

BTW: is there already a plugin that can do that? I might have missed it

[jspaezp]

I do not believe it is ... I do not believe it should be too hard to write tbh, I dont have time for it this week though. I'll give it a go next time.

Also ... it does not seem to be inherently a GFM feature (https://github.github.com/gfm/) (I would appreciate an example of it in "the wild", since I dont used the "macro")

[hukkin]

Thanks for the issue @jspaezp !

I'll have to consider whether I want the maintenance burden that this adds.

For now, as you mention, it is possible to use the pre-commit tool to achieve what you want. This means configuring mdformat and file inclusion/exclusion patterns in .pre-commit-config.yaml and running

pre-commit run mdformat

or

pre-commit run mdformat --files <filename>

instead of

mdformat <filename>

Is there a particular reason this does not suit your use case?

---

I think @juhannc could benefit from (currently unspecced and unimplemented) feature https://github.com/executablebooks/mdformat/issues/53 or alternatively a plugin that makes mdformat special case the particular [TOC] macro. There's a small bit of documentation on how to build a plugin here and a list of existing plugins (of which you can check the source code of) here

[jspaezp]

Hello @hukkin, the main use case I can think of is ...

If I change the configuration of my mdformat (lets say ... lines from 120 to 80), and I want to apply it to ALL of my files in the repo, I would much rather use mdformat . instead of mdformat *.md ; mdformat */*.md ; mdformat */*/*.md ; mdformat *.qmd ....

And in addition, it feels natural. It would be consistent with the behavior of many other formatting tools that are also released as pre-commit hooks.

• black .
• isort .
• pylint {python_module}
• ruff .
• pyright .
• mypy .

LMK what you think

[twmht]

this is an important feature since it violates the CHANGELOG.md generated by https://github.com/google-github-actions/release-please-action