Confusing "When to use" in readme (micromark vs remark)

[chrisjsewell]

Heya, here

and here (in Comparison):

I assume the "complex things" / "fine grained" control are meant to reference remark, rather than saying you should use micromark for both 😬 ?

[ChristianMurphy]

Micromark offers two things:

1. a low level parser
2. a minimally configurable markdown to html compiler

---

If you want to do really complex things with markdown

and

If you’re looking for fine grained control, use micromark

refer to the former, the low level parser

---

If you just want to turn markdown into HTML (with maybe a few extensions)

and

If you just want HTML from markdown, use micromark

refers to the latter, the minimally configurable markdown to html compiler

[chrisjsewell]

In the remark readme it also says:

i.e. micromark for simple things, remark for complex things,
which again is a bit cognitively dissonant

[ChristianMurphy]

Similarly, if micromark can be used for both fine-grained and simple use cases, why would you use remark?

i.e. micromark for simple things, remark for complex things, which again is a bit cognitively dissonant

it is not dissonant.
micromark lives on the edges of very simple and very complex.
remark lives in the large and happy medium between, and has a large ecosystem of plugins supporting this.

I think this should be explained then in the readme because, IMO, the "when to use" currently reads as "use it for everything, simple and complex", which is not very helpful

Pull requests improving the documentation are welcome!

[chrisjsewell]

Cheers, do you have any "examples" of something that would probably be too complex for remark, and instead you would use micromark.
I'm 99% sure that my use case is suited to remark, but wanted to check that I was not missing anything by prematurely "disregarding" micromark

[ChristianMurphy]

do you have any "examples" of something that would probably be too complex for remark, and instead you would use micromark.

Sure, a recent example is: mdx-js/mdx#1953
Adding a new syntax feature like {# heading-id } needs to happen in micromark, because it potentially overlaps with other syntax in markdown/mdx, and changes the initial AST structure.

Trying to handle this in remark would happen too late, in this case, because it already conflicted with a JSX syntax extension and caused an error before the remark plugin was even run.

That said, extending markdown syntax should be done with caution, as noted in https://github.com/micromark/micromark#extending-markdown alternatives, like working in remark are often preferable.

https://unifiedjs.com/learn has some guides on working with abstract syntax trees (like mdast/remark) which can help round out the understand of what's possible with ASTs a bit more.

[chrisjsewell]

That's great, thanks again. I'll do some more reading before I pester you again 😄