mdtoc - Markdown Table of Contents
Read Markdown files and output a table of contents.
Installation
Requirements:
- Ruby (see .ruby-version)
gem install mdtocUsage
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
<!-- mdtoc -->tag to a Markdown file.echo '<!-- mdtoc -->' >> README.md
-
Run
mdtocand 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
mdtocto update the generated table of contents in the ./README.md file -
git addany*.mdfiles - 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
endSee andornaut/til for an example.
Developing
Checks require Make and Docker. Project-owned stock image phases live in
tests/container/. Native checks use the declared runtime; Markdown and
ShellCheck use separate pinned images. Each phase uses project source and disposable scratch storage.
make check
bundle exec rake test
bundle exec rake rubocop
bundle exec rake sorbet
bundle exec rake buildThe full gate runs RuboCop, Sorbet, Markdown lint, the unit suite and gem
packaging. bundle exec rake build writes the gem under pkg/. Native Rake tasks run on the host.
Publishing
- Bump version in
lib/mdtoc/version.rb - Run
bundle installto updateGemfile.lock - Commit the changes
- Tag the commit
vX.Y.Zand 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.