How do I add permalinks to headers in kramdown?

jekyll anchor link
github pages anchors

I'm building a website with Jekyll and Github-Page written in markdown. I want to make it easy to permalink to headers, the way most online documentation does.

I want to get a URL with a hash when I click on a header. Is there an easy way to achieve this in Kramdown or in Jekyll's config?

Markdown page

#### A regular header

A regular sentence.

Ideal result

<h4 id="a-regular-header"><a href="#a-regular-header">A regular header</a></h4>
<p>A regular sentence.</p>

You can do this manually in the Markdown for each title:

#### [A regular header](#a-regular-header)

A regular sentence.

The downside there is the maintenance cost. Another option would be to create the links on the client side by adding this to the bottom of your chosen pages:

    var headings = document.querySelectorAll("h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]");

    for (var i = 0; i < headings.length; i++) {
        headings[i].innerHTML =
            '<a href="#' + headings[i].id + '">' +
                headings[i].innerText +

You could look into a plugin, modified Markdown parser or task runner like gulp.js to do this at build time if the JavaScript dependency doesn't suit your audience. You can't use these alternatives if you want GitHub Pages to build your page, but you can build locally and commit the output.

Syntax, If a header text gets too long for one line, you need to use HTML syntax instead. fenced code blocks It is not possible to create nested links! The link text may  Headers. kramdown supports so called Setext style and atx style headers. Both forms can be used inside a single document. Setext Style. Setext style headers have to start on a block boundary with a line of text (the header text) and a line with only equal signs (for a first level header) or dashes (for a second level header). The header text

You can use Jekyll plugins to override the standard behaviour. I put this in _plugins/header.rb:

class Jekyll::MarkdownHeader < Jekyll::Converters::Markdown
    def convert(content)
        super.gsub(/<h(\d) id="(.*?)">/, '<h\1 id="\2"><a href="#\2">§</a>')

The regexp replaces all headers with an ID tag with one that also adds a link. This is not a fool-proof way to do this in a generic case (e.g. <h2 class="foo" id="x") won't work), but the Kramdown output is fairly reliable and consistent, so it should be okay. I added this with Jekyll 3.8.4 and Kramdown 1.17.0.

If you want/need a more robust solution then you can use a HTML parser. Shouldn't be that much harder.

The advantage of this is that it doesn't require JavaScript on the client side.

Or if you want to link the actual heading instead of prepending a link:

class Jekyll::MarkdownHeader < Jekyll::Converters::Markdown
  def convert(content)
    super.gsub(/<h(\d) id="(.*?)">(.*)<\/h(\d)>/, '<h\1 id="\2"><a href="#\2">\3</a></h\1>')

Reference links in headers add link reference/name to header ID , Reference links in headers add link reference/name to header ID #252 have gotten a warning about that if you use the kramdown binary. Markdown Options. The various Markdown renderers supported by Jekyll sometimes have extra options available. Kramdown. Kramdown is the default Markdown renderer for Jekyll. Below is a list of the currently supported options: auto_id_prefix - Prefix used for automatically generated header IDs

This isn't possible from a generator standpoint without a Jekyll plugin. Since you're using GitHub Pages, that won't be possible since they don't support custom plugins.

A reasonable solution would be to create a script which finds all the headings with IDs and turns them into links or appends a link icon.

Add an option to add a link to the header ID at the end of the header , It would be cool to write: echo '# Header' | kramdown --id-link 'link' and GH pages along  The quick reference is for version 2.2.1 of the syntax documentation. kramdown has two main classes of elements: block and span-level elements. Block-level elements are used to create paragraphs, headers, lists and so on whereas span-level elements are used to markup text phrases as emphasized, as a link and so on.

If you want a GitHub Pages compatible way of doing this without JavaScript, you can get crazy creative with Liquid and carefully parse your rendered HTML as strings and manipulate it as such.

Or you could just use this snippet that does exactly that:

Developer Docs Style Guide with Markdown, Kramdown, YAML, There is another way to create links which does not interrupt the text flow. As discussed above, Headers and Sub Headers automatically  markdown: kramdown kramdown: input: GFM hard_wrap: false It works as expected (if you turn off the hard_wrap) :-) (Update Mar/23) Changed the broken links to the Planet Jekyll Syntax Highlighting Sandbox for examples.

Kramdown table of contents links when header is defined in table , Kramdown table of contents links when header is defined in table cell inside html block (tags) you need to add the “magic” markdown=1 attribute to your tag. In the Settings → Permalinks Screen, you can choose one of the more common permalink structures or enter your own in the “Custom structure” field using the structure tags. Please note: You do not put your site url in the permalinks fields. You only use one of the structure tags, or a combination of tags.

Markdown Kramdown Tips & Tricks, Kramdown itself will append an ID for each heading, automatically. The ID will be all the words in But they are specially useful for links, as in:. kramdown Documentation Overview. kramdown is first and foremost a library for converting text written in a superset of Markdown to HTML. However, due to its modular architecture it is able to support additional input and output formats.

Markdown Guide, Read through our Markdown kramdown Style Guide! Use relative links when referring to links found on For example, a link to our Just add it right below the heading, and it won't be included into the ToC. In fact no_toc is a​  Yoast SEO and permalinks. Yoast SEO is a must-have tool that makes SEO available to everyone. It’s an easy to use tool that helps you make a perfect website. For instance, if you install WordPress and don’t change the default permalink settings, Yoast SEO will urge you to change it.