Project

mdtoc

0.0
A long-lived project that still receives updates
mdtocandornaut/mdtocHomepageDocumentationSource CodeBug Tracker
# mdtoc - Markdown Table of Contents Read Markdown files and output a table of contents. ## Installation Requirements: * [Ruby](https://www.ruby-lang.org/en/) (see [.ruby-version](./.ruby-version)) ```bash gem install mdtoc ``` ## Usage ```bash 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. ```bash 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"). ```bash mdtoc -aco README.md test/samples ``` ## Example Rakefile Create a `Rakefile` with the contents below, then run [`rake`](https://github.com/ruby/rake) to: * `git pull` * `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 ```ruby 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 *.md **/*.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](https://github.com/andornaut/til/blob/master/Rakefile) for an example. ## Development ### Setup Requirements: * [Bundler](https://bundler.io/) * [chruby](https://github.com/postmodern/chruby) (recommended) ```bash # Setup development environment bin/setup ``` ### Tasks ```bash # 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
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
 Popularity
Downloads
6,258
Stars
1
Forks
0
Watchers
1
 Releases
Current version
0.4.0
Total releases
7
First release
2020-11-02
Latest release
2026-03-25
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
1
Merged Pull Requests
0
Pull Request Acceptance Rate
0%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2024-12-16
Reverse Dependencies
0

 Dependencies

Development

minitest
~> 6.0
rake
>= 0
rubocop
~> 1.50
rubocop-sorbet
~> 0.12.0
sorbet
>= 0
unparser
~> 0.8.0

Runtime

sorbet-runtime
>= 0
 Project Readme

mdtoc - Markdown Table of Contents

Read Markdown files and output a table of contents.

Installation

Requirements:

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:

# 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