Showdown: Set the ID of a heading

[kaycebasques]

Nice project, looks like it may suit my needs for my personal blog.

I like to create nice, concise heading IDs. In the developer.google.com/web docs we can do something like this:

## How to set heading IDs {: #ids }

Which converts to:

<h2 id="ids">How to set heading IDs</h2>

Do you support anything similar? Pretty sure it's not in the Markdown spec, so probably not.

I guess using HTML for the headings of my posts would be a workaround?

[tivie]

Showdown supports auto-generated headings by default (which I reckon does not meet your needs). Since that type of syntax is non standard, it's best suited for an extension, which can be easily created.

Here's an extension that accomplishes exactly what you want (See working fiddle here).

// a listener extension that supports custom ids with the following syntax
// # Header text {: #the-custom-id}
showdown.extension('custom-header-id', function () {
  var rgx = /^(#{1,6})[ \t]*(.+?) *\{: *#([\S]+?)\}[ \t]*#*$/gmi;

  return [{
    type: 'listener',
    listeners: {
      'headers.before': function (event, text, converter, options, globals) {
        text = text.replace(rgx, function (wm, hLevel, hText, hCustomId) {
          // find how many # there are at the beginning of the header
          // these will define the header level
          hLevel = hLevel.length;

          // since headers can have markdown in them (ex: # some *italic* header)
          // we need to pass the text to the span parser
          hText = showdown.subParser('spanGamut')(hText, options, globals);

          // create the appropriate HTML
          var header = '<h' + hLevel + ' id="' + hCustomId + '">' + hText + '</h' + hLevel + '>';

          // hash block to prevent any further modification
          return showdown.subParser('hashBlock')(header, options, globals);
        });
        // return the changed text
        return text;
      }
    }
  }];
});

Let me know if this works for you.

---

As you know, ShowdownJS is a free library and it will remain free forever. However, maintaining and improving the library costs time and money. Currently, we're looking to improve showdown with automated tests in all browsers and a proper domain and webpage. 500$ should be enough to to keep showdown testing framework running for a year or two.

If you like our work and find our library useful, please donate through Pledgie or directly through paypal!! Your contribution will be greatly appreciated.