Project

tocer

0.02
The project is in a healthy, maintained state
A command line interface for generating table of contents for Markdown files.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
 Project Readme

Tocer

Gem Version
Circle CI Status

Tocer (a.k.a. Table of Contenter) is a command line interface for generating table of contents for Markdown files.

Table of Contents
  • Features
  • Requirements
  • Setup
  • Usage
    • Command Line Interface (CLI)
    • Customization
    • Rake
  • Development
  • Tests
  • Versioning
  • Code of Conduct
  • Contributions
  • License
  • History
  • Credits

Features

  • Supports Markdown ATX-style headers. Example: # Header.

    • Does not support header suffixes. Example: # Header #.

    • Does not support header prefixes without spaces. Example: #Header.

  • Supports table of contents generation for single or multiple files.

  • Supports custom label. Default: ## Table of Contents.

  • Supports file list filtering. Default: "README.md".

  • Prepends table of contents to Markdown documents that don’t have table of contents.

  • Rebuilds Markdown documents that have existing table of contents.

Requirements

  1. A UNIX-based system.

  2. Ruby.

Setup

To install, run:

gem install tocer

Usage

Command Line Interface (CLI)

From the command line, type: tocer --help

tocer -c, [--config]         # Manage gem configuration.
tocer -g, [--generate=PATH]  # Generate table of contents.
tocer -h, [--help=COMMAND]   # Show this message or get help for a command.
tocer -v, [--version]        # Show gem version.

For specific --generate options, run tocer --help --generate to see the following:

-l, [--label=LABEL]             # Label
                                # Default: ## Table of Contents
-i, [--includes=one two three]  # File include list
                                # Default: ["README.md"]

To generate the table of contents at a specific position within your Markdown files, add the following lines to your file(s) prior to generation:

<!-- Tocer[start] -->
<!-- Tocer[finish] -->

Alternatively, you can run tocer -g <directory> on files that do not have Tocer support and it will prepend the table of contents to your file(s), complete with an auto-generated table of contents.

In the case that Tocer has already auto-generated a table of contents for a Markdown file, the existing table of contents has become stale, or placement of the table of contents has changed you can re-run Tocer on that file to auto-update it with new table of contents.

Customization

This gem can be configured via a global configuration: ~/.config/tocer/configuration.yml.

It can also be configured via XDG environment variables.

The default configuration is as follows:

:label: "## Table of Contents"
:includes:
  - "README.md"

Feel free to take this default configuration, modify, and save as your own custom configuration.yml.

The configuration.yml file can be configured as follows:

  • label: The header label for the table of contents. Default: "# Table of Contents".

  • includes: The list of included files. Default: "*.md".

There are multiple ways the include list can be defined. Here are some examples:

# Use an empty array to ignore all files (a key with no value would work too).
:includes: []

# Use an array of wildcards for groups of files with similar extensions:
:includes:
  - "*.md"
  - "*.mkd"
  - "*.markdown"

# Use a mix of wild cards and relative names/paths to customized as necessary:
:includes:
  - "README.md"
  - "docs/*.md"
  - "*.markdown"

# Use a recursive glob to traverse and update all sub-directories:
:includes:
  - "**/*.md"

Rake

You can add Rake support by adding the following to your Rakefile:

begin
  require "tocer/rake/setup"
rescue LoadError => error
  puts error.message
end

Once configured, the following tasks will be available (i.e. bundle exec rake -T):

rake toc[label,includes]   # Add/Update Table of Contents (README)

…which can be called as follows (quotes are not necessary if spaces are not used):

rake toc["## Example, *.md"]

Development

To contribute, run:

git clone https://github.com/bkuhlmann/tocer.git
cd tocer
bin/setup

You can also use the IRB console for direct access to all objects:

bin/console

Tests

To test, run:

bundle exec rake

Versioning

Read Semantic Versioning for details. Briefly, it means:

  • Major (X.y.z) - Incremented for any backwards incompatible public API changes.

  • Minor (x.Y.z) - Incremented for new, backwards compatible, public API enhancements/fixes.

  • Patch (x.y.Z) - Incremented for small, backwards compatible, bug fixes.

Code of Conduct

Please note that this project is released with a CODE OF CONDUCT. By participating in this project you agree to abide by its terms.

Contributions

Read CONTRIBUTING for details.

License

Read LICENSE for details.

History

Read CHANGES for details.

Credits

Engineered by Brooke Kuhlmann.