SixArm.com → Ruby →
Markdown table of contents gem

• Git: https://github.com/SixArm/sixarm_ruby_markdown_table_of_contents
• Doc: http://sixarm.com/sixarm_ruby_markdown_table_of_contents/doc
• Gem: https://rubygems.org/gems/sixarm_ruby_markdown_table_of_contents
• Contact: Joel Parker Henderson, joel@sixarm.com
• Project: changes, license, contributing.

Introduction

Update a markdown file by autogenerating a table of contents based on the markdown headlines.

Syntax:

markdown-table-of-contents [options] <file> ...

Example:

markdown-table-of-contents example.md

Limits:

• This processes H2 headlines and lesser; this deliberately does not process H1 headlines.

• This needs each headline anchor href to be unique; this deliberately does not do any disambiguation.

Options:

• -b --bullet STRING: set the line bullet (default is "*")

• -l --line-prefix STRING: set the line prefix (default is "")

• --min INTEGER: set the headline minimum level (default is 2, meaning H2 and higher; currently 1 does not work, as is a known issue)

• --max INTEGER: set the headline maximum level (default is 3, meaning H3 and lower)

• --headline-regex REGEXP: set the headline regular expression

• --contents-regex REGEXP: set the contents regular expression

Install

Gem

To install this gem in your shell or terminal:

gem install sixarm_ruby_markdown_table_of_contents

Gemfile

To add this gem to your Gemfile:

gem 'sixarm_ruby_markdown_table_of_contents'

Require

To require the gem in your code:

require 'sixarm_ruby_markdown_table_of_contents'

How it works

The command scans Markdown text for each Markdown headline, such as:

## Hello World

The command parses the headline to create a Markdown bullet list item link, such as:

• Introduction
• Install
  • Gem
  • Require
• How it works
• Hello World
• Technical specifics
• Demo
• Alpha
  • Bravo
  • Charlie
  • Delta
• Alpha
  • Bravo
  • Charlie
  • Delta
• Tracking

The command processes all the headlines into a Markdown bullet list, such as:

* [Hello World](#hello-world)
* [Your Headline Here](#your-headline-here)
* [Foo Bar](#foo-bar)

The command searches for text that indicates a blank placeholder for a table of contents:

* [](#)

The command replaces the blank placeholder with the Markdown bullet list.

Later on, you can run the command again, and the command will rescan the headlines, create a fresh Markdown bullet list, and replace the existing Markdown bullet list.

Technical specifics

The command does a search/replace for first occurence of this regular expression: ^\* \[.*?\]\(#.*?\)$ and continues until the regular expression doesn't match.

which matches the blank placeholder and also matches an existing Markdown bullet list of links and anchors.

Demo

Demonstration Markdown file text, before the generator:

# My Demo Page

* [](#)

## Alpha

### Bravo

#### Charlie

#### Delta

Example Markdown file text, after the generator:

# My Demo Page

* [Alpha](#alpha)
  * [Bravo](#bravo)
    * [Charlie](#charlie)
      * [Delta](#delta)

## Alpha

### Bravo

#### Charlie

#### Delta

Example of how GitHub renders the file, approximately:

<h1>Demo</h1>

TOC:
<ul>
  <li><a href="#alpha">Alpha</a></li>
  <li>
    <ul>
      <li><a href="#bravo">Bravo</a></li>
      <li>
        <ul>
          <li><a href="#charlie">Charlie</a></li>
          <li>
            <ul>
              <li><a href="#Delta">Delta</a></li>
            </ul>
          </li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

<h2><a class="anchor" href="#alpha" id="user-content-alpha">Alpha</a></h2>

<h3><a class="anchor" href="#bravo" id="user-content-bravo">Bravo</a></h2>

<h4><a class="anchor" href="#charlie" id="user-content-charlie">Charlie</a></h2>

<h5><a class="anchor" href="#delta" id="user-content-delta">Delta</a></h2>

The GitHub automatic rendering typically adds more information, such as an SVG anchor image that shows/hides during hover.

Tracking

• Command: markdown-table-of-contents
• Version: 3.1.0
• Created: 2018-02-04
• Updated: 2018-12-23
• License: Open source as described in the file LICENSE.md
• Contact: Joel Parker Henderson (joel@joelparkerhenderson.com)