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

Add a  tag to a Markdown file.
```
echo '' >> README.md
```
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.

Developing

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

Bump version in lib/mdtoc/version.rb
Run bundle install to update Gemfile.lock
Commit the changes
Tag the commit vX.Y.Z and push the tag

Pushing the tag is the whole release. The Release workflow runs the checks, builds the gem, cuts the GitHub release, and pushes that same gem to RubyGems. rake release is not run by hand.

Nothing here holds a RubyGems API key. The workflow authenticates with a short-lived credential minted from its own OIDC claim, against a trusted publisher registered on RubyGems that names this repository and .github/workflows/release.yml. Renaming that file stops publishing until the trusted publisher is updated to match.