:toc: macro :toclevels: 5 :figure-caption!:
Tocer
¶ ↑
- link=badge.fury.io/rb/tocer
-
image::badge.fury.io/rb/tocer.svg[Gem Version]
- link=www.alchemists.io/projects/code_quality
-
image::img.shields.io/badge/code_style-alchemists-brightgreen.svg[Alchemists Style Guide]
- link=circleci.com/gh/bkuhlmann/tocer
-
image::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. Use this tool to automatically manage and update your documentation with minimal effort. Works on single files or multiple files within nested directory structures.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. . 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
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-runTocer
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 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 # 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 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 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 CODE_OF_CONDUCT.adoc[CODE OF CONDUCT]. By participating in this project you agree to abide by its terms.
Contributions¶ ↑
Read CONTRIBUTING.adoc[CONTRIBUTING] for details.
License¶ ↑
Read LICENSE.adoc[LICENSE] for details.
History¶ ↑
Read CHANGES.adoc[CHANGES] for details.
Credits¶ ↑
Engineered by https://www.alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].
-
-
-