marked
marked copied to clipboard
markedjs
Default heading anchors can become really ugly👾
Marked version: 2.0.0
Describe the bug JSDOC-to-Markdown generates the following markdown:
#### HOOK.add(dstObj, triggers, fn, [priority]) ⇒ <code>Number</code>
which Marked then dutifully transforms into this monstrosity:
<h4 id="md-hookadddstobj-triggers-fn-priority-⇒-number">
To Reproduce Equiv. Marked Demo
Expected behavior Ideally Marked should more intelligently know when 'enough is enough' and stop parsing, in this instance it would be at the starting bracket. At the very least there should be a way to easily modify/replace the native anchor generating behaviour, RegEx being the 'easiest'.
Yes, I know this is a borderline feature request but the idea of linking to such an anchor disturbs me greatly.
Another alternative: since I can easily modify JSDOC2MD's output, an alternative would be a way to change default header generation so any instance of # [foo](#md-foo) would instead add md-foo as the header's ID, not transform it into a link
The ids are supposed to match GitHubs ids for headers in a readme
It looks like GitHub removes the arrow along with other special characters so it looks like:
hookadddstobj-triggers-fn-priority--number
this is a bug.
You can extend the renderer to override the id if you don't want it to match GitHub.
GitHub has some interesting behavior here. I'm seeing the following:
user-content-hookadddstobj-triggers-fn-priority--number
According to Babelmark 3, nearly every implementation has a different algorithm for generating IDs.
Looks like it is not documented anywhere either.
https://github.com/github/markup/issues/1326
It might be nice to use the unicode library to create the regexps like https://github.com/Flet/github-slugger/pull/35.
We would have to watch how much that adds to the minified file size.
The https://github.com/markedjs/marked-gfm-heading-id extension uses github-slugger to create the ids so it should be much closer to github. I think the small implementation we have in marked is good enough for most situations.
Also https://github.com/markedjs/marked-custom-heading-id can be used to create custom ids for headings