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

2. 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:

• Run mdtoc to update the generated table of contents in the ./README.md file
• git add any *.md files
• Git commit, pull, 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 = <<~CMD
    set -e
    if [ -n "$(git diff --name-only --diff-filter=U)" ]; then
      echo 'Error: conflicts exist' >&2
      exit 1
    fi
    mdtoc --append --create --output README.md docs/
    git add README.md docs/*.md
    git commit -qm 'Update TOC' || true
    git pull
    git push
  CMD
  sh command, verbose: false do |ok, status|
    unless ok
      fail "Failed with status: #{status.exitstatus}"
    end
  end
end

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

1. Bump version in lib/mdtoc/version.rb
2. Run bundle install to update Gemfile.lock
3. Commit the changes
4. Run rake release to publish the gem to RubyGems, create the git tag, and push