tocbot

TOCBot

• TOCBot
  • Introduction
  • Installation
  • Command Line Usage
    • Basic Usage
    • Advanced Usage
  • Contributing to TOCBot
    • Setup
    • Testing
  • To-Do List

Introduction

TOCBot is a Table of Content (TOC) creation robot. It works by reading a markdown file and identifying all of the headers and creating a table of contents based on those headers.

Default it includes all levels (# = level 1, ## = level 2, etc), and will include headers up to 5 levels deep.

It will insert the table of contents between the separators that are placed in the file. The default separator is .

There must be TWO separators, one to open the table of contents and one to close it.

TOCBot will also add links above each header in order to make the Table of Contents clickable.

Installation

Installing TOCBot is very simple, just execute the following command.

gem install tocbot

Command Line Usage

Option	Purpose	Default Value
-h or --help	Show the help message	N/A
-d or --depth	How many levels deep to add to the TOC.	5
-f or --filename	The name of the file to process.	README.md
-l or --level	The level of heading to start with.	1
-s or --separator	The separator used to show where to insert the TOC.	<!--TOCBot-->

Basic Usage

You can execute TOCBot by simple running

tocbot

Advanced Usage

Start with level 2 headers (exclude all level 1 headers), and only include 3 levels of headers.

tocbot -s 2 -d 3

The depth is measures from the start so the above example will include header levels 2, 3 & 4.

Contributing to TOCBot

Setup

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Testing

For local testing make sure that you run bundle exec rspec spec and then rake install to install the gem locally.

For further information please refer to the contributing documentation.

To-Do List

• Allow users to specify the separator
• Allow users to specify how deep into the headers to go
• Allow users to specify levels to skip