:toc: macro
:toclevels: 5
:figure-caption!:

= Tocer

[link=http://badge.fury.io/rb/tocer]
image::https://badge.fury.io/rb/tocer.svg[Gem Version]
[link=https://www.alchemists.io/projects/code_quality]
image::https://img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
[link=https://circleci.com/gh/bkuhlmann/tocer]
image::https://circleci.com/gh/bkuhlmann/tocer.svg?style=svg[Circle CI Status]

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

toc::[]

== 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

. A UNIX-based system.
. link:https://www.ruby-lang.org[Ruby].

== Setup

To install, run:

[source,bash]
----
gem install tocer
----

== Usage

=== Command Line Interface (CLI)

From the command line, run: `tocer --help`

....
USAGE:
  -b, --build [PATH]                       Build table of contents. Default path: "."
  -c, --config ACTION                      Manage gem configuration: edit or view.
  -h, --help                               Show this message.
  -v, --version                            Show gem version.

BUILD OPTIONS:
  -i, --includes [a,b,c]                   Include pattern list. Default: ["README.md"].
  -l, --label [LABEL]                      Label. Default: "## Table of Contents".
....

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:

[source,markdown]
----
<!-- Tocer[start] -->
<!-- Tocer[finish] -->
----

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 link:https://www.alchemists.io/projects/xdg[XDG] environment
variables.

The default configuration is as follows:

[source,yaml]
----
: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.
* `includes`: The list of included files.

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

[source,yaml]
----
# 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`:

[source,ruby]
----
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):

[source,bash]
----
rake toc["## Example, *.md"]
----

== Development

To contribute, run:

[source,bash]
----
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:

[source,bash]
----
bin/console
----

== Tests

To test, run:

[source,bash]
----
bundle exec rake
----

== Versioning

Read link:https://semver.org[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 link:CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By
participating in this project you agree to abide by its terms.

== Contributions

Read link:CONTRIBUTING.adoc[CONTRIBUTING] for details.

== License

Read link:LICENSE.adoc[LICENSE] for details.

== History

Read link:CHANGES.adoc[CHANGES] for details.

== Credits

Engineered by link:https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].