dramatic sunset photo of Portland's famed Fremont Bridge



Add a Table of Contents to Your Markdown Page

Tagged: Liquid ERB Markdown

Added by: @jaredcwhite @jaredcwhite

Tested on: Bridgetown v1.0

Bridgetown’s Markdown converter is called Kramdown, and it sports a variety of cool features—one of which is the ability to generate a table of contents based on headings throughout the content of a Markdown file. But the way to do that is a little non-obvious. Let’s create a Liquid tag/Ruby helper for that!

class Builders::Toc < SiteBuilder
  def build
    liquid_tag "toc", :toc_template
    helper "toc", :toc_template

  def toc_template(*)
      ## Table of Contents
      * …

This will add a Table of Contents heading which itself won’t show up in the TOC, and then use Kramdown’s special syntax to generate the TOC. Now you can use {% toc %} (Liquid), <%= toc %> (ERB), or {%= toc %} (Serbea) to place your TOC anywhere in a Markdown file.

Tip: If you’d rather have your TOC be numbered instead of just bullet points, use 1. instead of * for the blank list.

Return to Cards