How to add anchor links to Markdown headings?

[pftnhr]

I would like to have permalinks at the headlines like:

<h2 id="nice-headline">Nice Headline <a href="#nice-headline>#</a></h2>

I have already looked for extensions and also searched here in the discussions, but couldn't find anything.

Before I try to understand the toc extension and convert it into something suitable, I wanted to ask you if you might know something or can give me the decisive tip.

Many thanks in advance!

EDIT:
Maybe I found a solution. Will try it tomorrow.

[schulle4u]

I suppose you are looking for an automated solution? But just in case you missed the least invasive method, here's how to do this in markdown.

Adding an anchor link just after the markdown heading:

## Nice headline [#](#nice-headline) {#nice-headline}

In this case the heading ID has to be written separately as a special attribute, because the anchor link otherwise will become a part of the automatically generated ID. To avoid this, and also for accessibility reasons you could write down the anchor on the next line.

## Nice headline
[#](#nice-headline)

Markdown is fun! 😁

[pftnhr]

I definitely prefer an automated solution 😄 But if that doesn't work, for whatever reason, I now have a good work around thanks to you.

[GiovanniSalmeri]

It seems that PHP Markdown, the standard parser used by Yellow, does allow a function to achieve this:

header_id_func = null
Headers can have their id attribute auto-generated by setting this configuration variable to a function:

$parser->header_id_func = function ($text) {
    return preg_replace('/[^a-z0-9]/', '-', strtolower($text));
};

When I have time, I will give a glance to markdown.php in order to understand if this can be done with a small extension.

[pftnhr]

Hi Giovanni,

the ID is already given to the heading. If not, the ID is generated by the JavaScript. By the way, the instructions here work without any problems: https://attacomsian.com/blog/deep-anchor-links-javascript

[markseuffert]

You could do this client-side with JavaScript, another alternative is to do this server-side with an extension. The API for developers provides events you can handle in your own extension. For example onParseContentHtml() lets you modify the HTML output of the Markdown parser. For a practical example see the toc extension. As far as I know, mouseover anchor links are typically used in technical documentation and there are multiple styles. For example GitHub-style documentation adds the anchor link at the beginning of a heading, Python-style documentation adds the anchor link at the end of a heading.

[pftnhr]

Hi Mark,

I made it client-side with JavaScript, see my comment above.

[markseuffert]

First make it work, then make it better. 😀

The advantage with a server-side extension would be that it avoids website bloat. [1] [2] An extension can generate the necessary HTML and then you don't need JavaScript. We could add such a feature directly to the Markdown parser, but I think it would be better suited as its own extension. Because there is no agreement on where anchor links should be placed and what they should look like. You probably want some system settings for customisation. In any case, I am glad you found a solution that works and perhaps someone wants to write an extension in the future.

[pftnhr]

These are great links and I completely understand the problem. Why dump the burden on the user? Only my lack of programming skills keeps me from trying it as an extension. So there is still hope! 😅