search

kivikakk / comrak

CommonMark + GFM compatible Markdown parser and renderer
Other
1.12k stars 133 forks source link

Can `comrak` format directories recursively? #376

Closed bioinformatist closed 2 months ago

bioinformatist commented 2 months ago

Just as cargo fmt behaves.

Since most users prefer comrak for blogging rather than Rust development, it may not be suitable for them.

Perhaps we can provide the function via a parameter such as -r.

kivikakk commented 2 months ago

I'd be happy to accept such a feature. There are some questions to be pondered, though:

  1. What file extensions would such a recursive option look for? Not every .md file is necessarily CommonMark, and there's a variety of other extensions used for Markdown, any of which may or may not be CommonMark. Doing an in-place format of non-CommonMark Markdown files would change their meaning.
  2. Comrak takes many options. Accidentally doing an in-place format without the correct options for a given set of documents would alter them in a way that can't be easily reversed. Of course, we'd hope that users would have version control etc. and could mitigate such issues, but I think it highlights (in addition with (1)) the dangers of treating it like a code-formatting tool: it's a far cry from go fmt (which takes no configuration whatsoever), and we don't have a standard configuration file like rustfmt.toml. (We do have a config file, but it specifies only command-line arguments, which are not versioned and therefore don't represent a stable interface.)
  3. We might want a single file in-place formatting mode first. Comrak doesn't take any "subcommands", so we'd probably want something like comrak -i FILE which is equivalent to comrak FILE -t commonmark -o FILE.
kivikakk commented 2 months ago

Also;

Since most users prefer comrak for blogging rather than Rust development, it may not be suitable for them.

I'm not so sure about that. Comrak is heavily depended-upon in crates.io; I don't have any figures for how many folks are invoking it directly at the CLI, but I'd be surprised if it was anywhere near as many as direct + indirect library users.

bioinformatist commented 2 months ago

We might want a single file in-place formatting mode first. Comrak doesn't take any "subcommands", so we'd probably want something like comrak -i FILE which is equivalent to comrak FILE -t commonmark -o FILE.

I agree with it. Do you mind if I implement it? Also, do you think we can make Comrak a formatter for VS code (an extension like Black, Prettier, etc.) by this mode?

Then we can call Comrak for a specific file by CMD + Shift + P -> Format Document. This may be an alternative approach avoids issue (1) and (2).

kivikakk commented 2 months ago

I agree with it. Do you mind if I implement it?

That would be lovely; thank you!

Also, do you think we can make Comrak a formatter for VS code (an extension like Black, Prettier, etc.) by this mode?

Yep, that should be relatively(?) simple! I don't know the exact procedure for making such an extension, but I imagine we'd either supply binaries for the relevant architectures, or even use WASM for this (we already do a WASM build as part of CI) — presumably there are other VS Code extensions that do similar.