search

valeriangalliat / markdown-it-anchor

A markdown-it plugin that adds an `id` attribute to headings and optionally permalinks.
The Unlicense
291 stars 72 forks source link

Advice for keeping permalink symbol token stable #98

Closed meteorlxy closed 3 years ago

meteorlxy commented 3 years ago

We were using html_block token for permalink symbol in v7.x:

https://github.com/valeriangalliat/markdown-it-anchor/blob/828401d92c29ccf2420ed454c9c0cc6616aadedb/index.js#L24

Since v8.x, it's changed to html_inline (which is not the "exact" legacy implementation):

https://github.com/valeriangalliat/markdown-it-anchor/blob/f5c0844dbb0ea127fc158249411c1400a060c039/permalink.js#L31

It's an internal / undocumented breaking change, which might break some plugins that depend on markdown-it-anchor.

For example, we have a custom toc plugin, allowing html_inline in the heading to be displayed in the toc headers. Now we need one more step to filter the symbol token.

This issue is just a reminder in case next time you may change it unintentionally.

You can close it after reading 😄 @valeriangalliat

BTW, do you have any advices for how to filter the permalink symbol token, and keep other html_inline tokens?

valeriangalliat commented 3 years ago

Ouuh, good catch, the legacy version should be identical in all points, I'll publish a patch for this

As for your question, I think that including the toc plugin before markdown-it-anchor would solve the problem, since the toc would be generated before the anchors are added to the token stream?

valeriangalliat commented 3 years ago

The legacy permalink is compliant with the actual legacy implementation in 8.0.5!

meteorlxy commented 3 years ago

As for your question, I think that including the toc plugin before markdown-it-anchor would solve the problem, since the toc would be generated before the anchors are added to the token stream?

We are using the slug generated by markdown-it-anchor (i.e. id attr of the heading_open token) as the href link of the toc, so it's better to generate toc after anchor.

meteorlxy commented 3 years ago

@valeriangalliat Is it possible to add a meta.isPermalinkSymbol (or similar) to the symbol token? 🤔

valeriangalliat commented 3 years ago

Ah I see, makes sense. meta.isPermalinkSymbol seems like a great idea indeed! I've made a PR for this, https://github.com/valeriangalliat/markdown-it-anchor/pull/99, feel free to test against it (npm i valeriangalliat/markdown-it-anchor#feature/permalink-symbol-meta) and let me know if that solves your problem :)