mdtoc - Markdown Table of Contents

Read Markdown files and output a table of contents.

Installation

Requirements:

• Ruby (see .ruby-version)

gem install mdtoc

Usage

$ mdtoc --help
Usage: mdtoc [options] files or directories...
    -h, --help                       Show this message
    -o, --output PATH                Update a table of contents in the file at PATH
    -a, --[no-]append                Append to the --output file if a <!-- mdtoc --> tag isn't found
    -c, --[no-]create                Create the --output file if it does not exist

1. Add a <!-- mdtoc --> tag to a Markdown file.

  echo '<!-- mdtoc -->' >> README.md

1. Run mdtoc and specify input files or directories (eg. the "test/samples" directory) and an output file (eg. "README.md").

  mdtoc -aco README.md test/samples

Example Rakefile

Create a Rakefile with the contents below, then run rake to:

• git pullgem push pkg/mdtoc-0.2.0.gem
• git add any *.md files
• Run mdtoc to update the generated table of contents in the ./README.md file
• Git commit and push any changes

task default: %w[mdtoc]

desc 'Update Markdown table of contents and push changes to the git repository'
task :mdtoc do
  command = "    set -e\n    if [ -n \"$(git diff --name-only --diff-filter=U)\" ]; then\n      echo 'Error: conflicts exist' >&2\n      exit 1\n    fi\n    mdtoc --append --create --output README.md docs/\n    git add *.md **/*.md\n    git commit -qm 'Update TOC' || true\n    git pull\n    git push\n  CMD\n  sh command, verbose: false do |ok, status|\n    unless ok\n      fail \"Failed with status: \#{status.exitstatus}\"\n    end\n  end\nend\n"

See andornaut/til for an example.

Development

Setup

Requirements:

• Bundler
• chruby (recommended)

# Setup development environment
bin/setup

Tasks

# List rake tasks
$ rake -T
rake build                    # Build gem into the pkg directory
rake default                  # Run the build, rubocop, sorbet and test tasks
rake install                  # Build and install gem into system gems
rake rubocop                  # Run RuboCop
rake sorbet                   # Run the Sorbet type checker
rake test                     # Run tests

Run mdtoc with test inputs

$ ruby -Ilib bin/mdtoc test/samples

Run mdtoc with test inputs, and write to a newly created output file

$ f=$(mktemp) && ruby -Ilib bin/mdtoc -aco $f test/samples ; cat $f

### Publishing

```bash
rake release