Using a custom Redcarpet renderer?

#1

I’m looking to recreate the page anchor feature in GitHub, where all the headings automatically get page anchors.

I’ve already created my own table of contents so this other issue doesn’t apply. I just want <a name="getting-started">...</a> in my headings.

I’ve also been scanning the Redcarpet repo for related issues, and found two. As a result, I’ve created a custom Redcarpet::Render for this purpose (based on this gist). When run on its own, it works great. But I can’t get Middleman to use it.

tl;dr How do I get Middleman to use my custom Redcarpet renderer for creating Github-style page anchors on all my generated pages?

Here’s my config:

set :markdown_engine, :redcarpet
set :markdown, :tables => true, :autolink => true, :gh_blockcode => true, :fenced_code_blocks => true, :with_toc_data => true
#2

Hi @michele,

You can override the renderer by passing the renderer option in the markdown setting:

set :markdown_engine, :redcarpet
set :markdown, renderer: MichelesRenderer

Middleman actuallly uses its own renderer for Redcarpet, which allows links and images to work with Middleman, so you might want to make sure your renderer lines up with that behaviour, too.

However, if all you’re looking for is an anchor to use with URLs, setting with_toc_data: true does this for you. It generates <h1 id="getting-started">...</h1> tags, which work fine as anchor links (e.g. /page.html#getting-started).

Hope that helps!

2 Likes