https://github.com/containerscrew/mtoc
📄 Git markdown table of contents generator built with Rust.
https://github.com/containerscrew/mtoc
cargo clap cli crates-io git markdown rust table-of-contents table-of-contents-generator
Last synced: about 1 year ago
JSON representation
📄 Git markdown table of contents generator built with Rust.
- Host: GitHub
- URL: https://github.com/containerscrew/mtoc
- Owner: containerscrew
- License: agpl-3.0
- Created: 2024-08-27T09:33:48.000Z (almost 2 years ago)
- Default Branch: main
- Last Pushed: 2025-05-27T20:15:56.000Z (about 1 year ago)
- Last Synced: 2025-05-27T21:26:11.614Z (about 1 year ago)
- Topics: cargo, clap, cli, crates-io, git, markdown, rust, table-of-contents, table-of-contents-generator
- Language: Rust
- Homepage:
- Size: 307 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
mtoc 📄
Markdown table of contents generator
Built with ❤ in Rust
**Table of Contents** *generated with [mtoc](https://github.com/containerscrew/mtoc)*
- [Introduction](#introduction)
- [Badges](#badges)
- [Supported Platforms](#supported-platforms)
- [Installation](#installation)
- [Install latest binary version](#install-latest-binary-version)
- [Install specific binary version](#install-specific-binary-version)
- [Install using cargo](#install-using-cargo)
- [Uninstall](#uninstall)
- [Usage](#usage)
- [Help](#help)
- [Generate TOC](#generate-toc)
- [Generate TOC for a specific directory](#generate-toc-for-a-specific-directory)
- [Exclude directories from search](#exclude-directories-from-search)
- [Generate TOC for a specific file](#generate-toc-for-a-specific-file)
- [Using pre-commit](#using-pre-commit)
- [Example](#example)
- [Local development](#local-development)
- [IN PROGRESS](#in-progress)
- [License](#license)
# Introduction
**From this:**
```markdown
# Hello
## World
### How are you?
```
**To this:**
```markdown
**Table of Contents** *generated with [mtoc](https://github.com/containerscrew/mtoc)*
- [Hello](#hello)
- [World](#world)
- [How are you?](#how-are-you?)
```
# Badges
| | |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Total downloads | |
| Language |  |
| Crates |  |
| Github Release | [](https://github.com/containerscrew/mtoc/releases/latest) |
| Code |  |
| CI - Build | [](https://github.com/containerscrew/mtoc/actions/workflows/build.yml) |
| CI - Release | [](https://github.com/containerscrew/mtoc/actions/workflows/release.yml) |
| CI - Test | [](https://github.com/containerscrew/mtoc/actions/workflows/test.yml) |
| CI - Coverage | [](https://github.com/containerscrew/mtoc/actions/workflows/coverage.yml) |
| Meta | [](https://github.com/pre-commit/pre-commit) [](/LICENSE) |
| Codecov | [](https://codecov.io/github/containerscrew/mtoc) |
# Supported Platforms
| Arch | ARM64 | AMD64 |
|---------|------|------|
| darwin | ✅ | ✅ |
| linux | ✅ | ✅ |
| windows | ❌ | ❌ |
> Maybe in windows systems this tool will work, but has not been tested
# Installation
## Install latest binary version
```shell
curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/mtoc/main/install.sh | sh
```
## Install specific binary version
```shell
curl --proto '=https' --tlsv1.2 -sSfL https://raw.githubusercontent.com/containerscrew/mtoc/main/install.sh | sh -s -- -v "v0.8.0"
```
## Install using cargo
* **[Install Cargo](https://rustup.rs/)**
```shell
cargo install mtoc
```
> If you want to update the tool to a new version, just the run the same command `cargo install mtoc`.
# Uninstall
Binary:
```bash
sudo rm /usr/local/bin/mtoc
```
With cargo:
```shell
cargo uninstall mtoc
```
# Usage
By default, the command will search for markdown files in the current directory and generate the table of contents for each file. But, you can specify a directory to search for markdown files, specify only a specific file, or exclude directories from the search.
## Help
```bash
$ mtoc --help
Git markdown table of contents generator.
Usage: mtoc [OPTIONS]
Options:
-d, --directory Directory to search for markdown files [default: .]
-e, --exclude-dir ... Exclude directories from search
-f, --file ... Only generate TOC for the specified file(s)
-h, --help Print help
-V, --version Print version
```
## Generate TOC
```bash
mtoc # default the current dir where the command is executed. All the files, all the directories will be scanned.
```
## Generate TOC for a specific directory
```bash
mtoc -d /path/to/directory
```
## Exclude directories from search
```bash
mtoc -e ".target/" -e ".node_modules/"
```
## Generate TOC for a specific file
```bash
mtoc -f README.md
```
# Using pre-commit
Add this configuration to your `.pre-commit-config.yaml`
```yaml
- repo: https://github.com/containerscrew/mtoc
rev: v0.5.0 # use the most recent tag
hooks:
- id: mtoc
args: [ "-e", ".target/" ]
```
> Always stay up to date with the latest changes in the project markdown files.
# Example
```bash
$ mtoc -e ".target/" 🦀 v1.80.1
Excluding directories [".target/"]
Updated markdown file ./docs/test.md
Updated markdown file ./CHANGELOG.md
Updated markdown file ./README.md
```
# Local development
1. Make your changes
2. Run pre-commit
3. Test and build pipelines must pass
```bash
$ pre-commit install
# Or run once
$ pre-commit run -a
```
# IN PROGRESS
[IN PROGRESS](./docs/todo.md)
# License
`mtoc` is distributed under the terms of the [`GNU AFFERO GENERAL PUBLIC LICENSE`](./LICENSE).