TOCBot
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 <!--TOCBot-->.
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
- [X] Allow users to specify the separator
- [X] Allow users to specify how deep into the headers to go
- [X] Allow users to specify levels to skip