kubernetes-sigs / mdtoc

Markdown table-of-contents generator

Markdown Table of Contents Generator

mdtoc is a utility for generating a table-of-contents for markdown files.

Only github-flavored markdown is currently supported, but I am open to accepting patches to add other formats.

Table of Contents

Generated with mdtoc --inplace README.md

• Usage
• Installation
• Community, discussion, contribution, and support
  • Code of conduct

Usage

Usage: mdtoc [OPTIONS] [FILE]... Generate a table of contents for a markdown file (github flavor).

TOC may be wrapped in a pair of tags to allow in-place updates:

<!-- toc -->
generated TOC goes here
<!-- /toc -->

TOC indentation is normalized, so the shallowest header has indentation 0.

Options:

--dryrun - Whether to check for changes to TOC, rather than overwriting. Requires --inplace flag. Exit code 1 if there are changes.

--inplace - Whether to edit the file in-place, or output to STDOUT. Requires toc tags to be present.

--skip-prefix - Whether to ignore any headers before the opening toc tag. (default true)

For example, with --skip-prefix=false the TOC for this file becomes:

- [Markdown Table of Contents Generator](#markdown-table-of-contents-generator)
- [Table of Contents](#table-of-contents)
  - [Usage](#usage)
  - [Installation](#installation)

Installation

On linux, simply download and run the standalone release binary

# Optional: Verify the file integrity - check the release notes for the expected value.
$ sha256sum $BINARY
$ chmod +x $BINARY

Or, if you have a go development environment set up:

go get sigs.k8s.io/mdtoc

Community, discussion, contribution, and support

Learn how to engage with the Kubernetes community on the community page.

You can reach the maintainers of this project at:

• Slack
• Mailing List

Code of conduct

Participation in the Kubernetes community is governed by the Kubernetes Code of Conduct.

mdtoc's Issues

Limit Header depth for TOC?

kubernetes/enhancements#2407

I'd like to still use markdown for PRR questions, but I don't want some headers to show up in the TOC.

I'd propose something like --max-header-depth (defaults to 6 as per markdown). We could set that to 5 in enhancements, and use ###### Question text instead of <h4>Question text</h4>.

Thoughts?

Binary missing since version v1.0.1

I've noticed that since version v1.0.1, the binary file is no longer available for download.

However, the documentation suggests that you only need to download this binary to use the software.

Would it be possible to make this file available again? Manual compilation can be quite tedious, and I think the availability of the binary would make installation much easier for many users.

Thanks in advance

Setup CI

See kubernetes/org#1875 (comment)

Prow job should minimally:

1. Build tool
2. Run unit tests

Nice to have:

3. hack/verify-all.sh (currently just verify-boilerplate)