Syntax highlighting and other plugins in remark-react

[tremby]

I have remark-react integrated into my project and want to get some syntax highlighting.

I found this issue remarkjs/remark-react#14 which was closed via remarkjs/remark-react#30 which added a note to the readme about how to configure syntax highlighting.

However, that note was removed again a couple of commits on that file later, and the closest thing remaining is a link to the integrations docs of remark-html with the note "See how to integrate with other remark plugins in the Integrations section of remark-html." This is confusing to me because I was under the impression that remark-html was an alternative renderer, totally separate from remark-react. Perhaps I'm mistaken about that.

I looked at that linked page and the first plugin mentioned is remark-autolink-headings, which sounded good too, so I installed that. But I'm not seeing any difference in the output from remark-react: no links on the headings, no anchors on them either.

I tried remark-highlight.js too but I don't see any difference after installing that either.

I'm now trying remark-react-lowlight which is what was suggested briefly in that readme, and it does seem to be working. I wonder if there's some missing documentation here -- is there some way to tell which plugins are compatible with remark-react and which are not? Or is there some trick to configuring these plugins correctly I'm missing?

[wooorm]

Sorry, it seems I haven‘t answered here, but I do remember similar conversations somewhere else (maybe with someone else?)
Is there anything I can still help with?

[tremby]

I think it was probably me. Maybe elsewhere on Github or maybe on Discord.

The problem with remark-autolink-headings was that it wasn't at all obvious I also needed to install remark-slug. The docs for it seem clear now, and I'm not sure if I just understand it better or if it was edited to make it clearer.

I don't remember what the issue with remark-highlight.js was, or whether I gave up on it. I ended up using remark-react-lowlight.

I think it would be a good idea to improve the documentation of remark-react to make it clearer how to use plugins. As I said in the first post of this thread a couple of weeks ago, the current docs are confusing in that it tells us to look at the remark-html docs. That initially made me think I needed to install remark-html too and somehow use both remark-react and remark-html. But it turns out that they are alternatives, which again makes it weird that I'm sent to the documentation for the one I'm not using. I understand now that they are configured in similar ways, but that's not obvious from how the remark-react docs are worded ("See how to integrate with other remark plugins in the Integrations section of remark-html"). Maybe even as simple a change as this:

remark-react is very similar in configuration to remark-html. They are alternative renderers, so you'll want one or the other rather than both, but setting up plugins for either is done in the same way. As such, you can see how to integrate with other remark plugins in the Integrations section of remark-html's documentation.

[wooorm]

I added that a month ago indeed!

I like you suggestion for remark-react!

[wooorm]

done: remarkjs/remark-react@d4311dd

[tremby]

I added that a month ago indeed!

Hm in that case I still missed it when first trying to install the plugin.

I suggest taking it out of the blockquote (Github styles the blockquote in a muted colour; it looks less important) and adding a splash of bold, and perhaps also changing the wording, since it isn't exactly remark-slug which is important but rather than the headings having IDs. Maybe this: "This package does not add IDs. IDs must already be on the headings, which can be done automatically by using remark-slug before remark-autolink-headings."

There's also a code comment in the example:

Note that this module must be included after `remark-slug`.

I think this could be clearer.

Perhaps IDs need to be added before `remark-autolink-headings`, which we're doing here with `remark-slug`.

Maybe you think all of this is overkill, but I don't. ☺

[wooorm]

Thanks for the suggestions. I’ve pushed an update: remarkjs/remark-autolink-headings@a9c3e70.

I don’t agree on bolding: the readme already starts with three notes (the last temporary but most important). The other two have similar importance, adding bold to one shifts focus from the other