Project

mdtoc

0.0
The project is in a healthy, maintained state
# 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)) ``` $ 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`](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 ``` task default: %w[mdtoc] desc 'Update Markdown table of contents and push changes to the git repository' task :mdtoc do |t| command = <<~END set -e git pull 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 -m 'Update TOC' git push END %x|#{command}| end ``` See [andornaut/til](https://github.com/andornaut/til/blob/master/Rakefile) for an example. ## Development ### Installation Requirements: * [Bundler](https://bundler.io/) ``` # Install dependencies $ bundle ``` ### Usage ``` # List rake tasks $ rake -T rake build # Build mdtoc-0.0.2.gem into the pkg directory rake default # Run the build, rubocop:auto_correct, sorbet and test tasks rake install # Build and install mdtoc-0.0.2.gem into system gems rake install:local # Build and install mdtoc-0.0.2.gem into system gems without... rake release[remote] # Create tag v0.0.2 and build and push mdtoc-0.0.2.gem to ru... rake rubocop # Run RuboCop rake rubocop:auto_correct # Auto-correct RuboCop offenses 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} ```
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
 Dependencies

Development

Runtime

 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
  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 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
task default: %w[mdtoc]

desc 'Update Markdown table of contents and push changes to the git repository'
task :mdtoc do
  command = <<~CMD
    set -e
    git pull
    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 -m 'Update TOC'
    git push
  CMD
  %x|#{command}|
end

See andornaut/til for an example.

Development

Installation

Requirements:

# Install dependencies
$ bundle

Usage

# List rake tasks
$ rake -T
rake build                 # Build mdtoc-0.0.2.gem into the pkg directory
rake default               # Run the build, rubocop:auto_correct, sorbet and test tasks
rake install               # Build and install mdtoc-0.0.2.gem into system gems
rake install:local         # Build and install mdtoc-0.0.2.gem into system gems without...
rake release[remote]       # Create tag v0.0.2 and build and push mdtoc-0.0.2.gem to ru...
rake rubocop               # Run RuboCop
rake rubocop:auto_correct  # Auto-correct RuboCop offenses
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}