Skip to content

pholleran/toc-me

Repository files navigation

Build Status

toc-me

A GitHub App built with Probot that runs markdown-toc

Overview

Teams often use GitHub to manage documentation. As that documentation grows navigation can become a challenge, leading to the addition of a table of contents (ToC). As the documentation is modified team members must take care to ensure the ToC links are properly nested and formatted, which can create a barrier to contribution.

This app examines each push operation for markdown files formatted to use markdown-toc. When such files are found, toc-me regenerates a new ToC for the file and inserts it in the configured location.

Setup

Deploy and configure the app

The probot deployment docs can be followed to deploy your own version of toc-me. You will need to define an additional environment variable APP_NAME and populate it with the exact name of your GitHub App.

Configuring markdown files for TOC

toc-me will run on properly configured markdown files

Inserting a new TOC in a markdown file

Edit your markdown file to include the following line where you would like the ToC inserted:

<!-- toc -->

Updating an existing TOC

toc-me will automatically update a ToC previously generated by the app.

Configuration options

toc-me supports the optional use of a toc.yml configuration file in the .github directory of repositories in wihch the app is installed. Parameters supported by markdown-toc can be defined in the file.

For example:

append: 'this string will be appended to the end of the ToC'

Contributing

If you have suggestions for how toc-me could be improved, or want to report a bug, open an issue! We'd love all and any contributions.

For more, check out the Contributing Guide.

License

ISC © 2018 Philip Holleran pholleran@github.com

About

A GitHub App built with Probot that runs markdown-toc

Topics

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published