Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/pholleran/toc-me

A GitHub App built with Probot that runs markdown-toc
https://github.com/pholleran/toc-me

probot probot-app

Last synced: 19 days ago
JSON representation

A GitHub App built with Probot that runs markdown-toc

Host: GitHub
URL: https://github.com/pholleran/toc-me
Owner: pholleran
License: isc
Created: 2018-06-26T15:02:26.000Z (over 6 years ago)
Default Branch: master
Last Pushed: 2019-08-15T17:42:11.000Z (over 5 years ago)
Last Synced: 2025-01-01T12:03:11.866Z (23 days ago)
Topics: probot, probot-app
Language: JavaScript
Homepage: https://github.com/apps/toc-me
Size: 70.3 KB
Stars: 16
Watchers: 4
Forks: 5
Open Issues: 3
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

README

[![Build Status](https://dev.azure.com/pholleran/toc-me/_apis/build/status/toc-me-CI?branchName=master)](https://dev.azure.com/pholleran/toc-me/_build/latest?definitionId=6&branchName=master)

# toc-me

> A GitHub App built with [Probot](https://github.com/probot/probot) that runs [markdown-toc](https://github.com/jonschlinkert/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](https://probot.github.io/docs/deployment/) 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:

```

#### 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](https://github.com/jonschlinkert/markdown-toc#options) can be defined in the file.

For example:

```yaml
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](CONTRIBUTING.md).

## License