Updated 2023-08-14 by Rob Lauer rlauer6@comcast.net
A quick search regarding how to get a table of contents into my markdown yielded only a few hits or projects that seemed a little weighty to me, so here's a little Perl script with just a few dependencies that you might find useful. See Usage for more information.
The script will render your markdown as HTML using either the GitHub API or the Perl module Text::Markdown::Discount
A default stylesheet will be applied but you can provide your own style sheet as well.
The script has been tested with these versions, but others might work too.
| Module | Version |
|---|---|
Class::Accessor::Fast |
0.51 |
Date::Format |
2.24 |
HTTP::Request |
6.00 |
IO::Scalar |
2.113 |
JSON |
4.03 |
LWP::UserAgent |
6.36 |
Readonly |
2.05 |
git clone https://github.com/rlauer6/markdown-utils.git
make
sudo ln -s $(pwd)/markdown-utils/md-utlils.pl /usr/bin/md-utils
If you want to build an rpm for a RedHat Linux based system, install
the rpm-build tools.
make rpm
sudo yum install 'perl(Markdown::Render)'
cpanm -v Markdown::Render
usage: md-utils options [markdown-file]
Utility to add a table of contents and other goodies to your GitHub
flavored markdown.
- Add @TOC@ where you want to see your TOC.
- Add @TOC_BACK@ to insert an internal link to TOC
- Add @DATE(format-str)@ where you want to see a formatted date
- Add @GIT_USER@ where you want to see your git user name
- Add @GIT_EMAIL@ where you want to see your git email address
- Use the --render option to render the HTML for the markdown
Examples:
---------
md-utils README.md.in > README.md
md-utils -r README.md.in
Options
-------
-B, --body default is to add body tag, use --nobody to prevent
-b, --both interpolates intermediate file and renders HTML
-c, --css css file
-e, --engine github, text_markdown (default: github)
-h help
-i, --infile input file, default: STDIN
-m, --mode for GitHub API mode is 'gfm' or 'markdown' (default: markdown)
-n, --no-titl do not print a title for the TOC
-o, --outfile outfile, default: STDOUT
-r, --render render only, does NOT interpolate keywords
-R, --raw return raw HTML from engine
-t, --title string to use for a custom title, default: "Table of Contents"
-v, --version version
Tips
----
* Use !# to prevent a header from being include in the table of contents.
Add your own custom back to TOC message @TOC_BACK(Back to Index)@
* Date format strings are based on format strings supported by the Perl
module 'Date::Format'. The default format is %Y-%m-%d if not format is given.
* use the --nobody tag to return the HTML without the <html><body></body></html>
wrapper. --raw mode will also return HTML without wrapper
- Add @TOC@ somewhere in your markdown
- Use !# to prevent heading from being part of the table of contents
- Finalize your markdown...
cat README.md.in | md-utils.pl > README.md - ...or...kick it old school with a
Makefileif you likeFILES = \ README.md.in MARKDOWN=$(FILES:.md.in=.md) HTML=$(MARKDOWN:.md=.html) # interpolate the custom markdown keywords $(MARKDOWN): % : %.in md-utils $< > $@ $(HTML): $(MARKDOWN) md-utils -r $< > $@ all: $(MARKDOWN) $(HTML) markdown: $(MARKDOWN) html: $(HTML) clean: rm -f $(MARKDOWN) $(HTML) - ...and then...
make all
Add the current date using a custom format. Essentially calls the
Perl function time2str. See perldoc Date::Format.
If no format is present the default is %Y-%m-%d (YYYY-MM-DD).
Best practice would be to use a Makefile to generate your final
README.md from your README.md.in template as shown
above and generate your README.md as the last step before
pushing your branch to a repository.
Example:
@DATE(%Y-%m-%d)@
If you've done something like:
git config --global user.name "Fred Flintstone"
git config --global user.email "fflintstone@bedrock.org"
or
git config --local user.name "Fred Flintstone"
git config --local user.email "fflintstone@bedrock.org"
...then you can expect to see those in your markdown, otherwise don't use the tags.
Add this tag anywhere in your markdown in include a table of contents.
Add @TOC_BACK@ anywhere in your markdown template to insert an internal link back to the table of contents.
@TOC_BACK@
@TOC_BACK(Back to Index)@
Use the --no-title option if you don't want the script to insert a
header for the TOC.
Use the --title option if you want a custom header for the TOC.
Precede the heading level with bang (!) and that heading will not be included in the table of contents.
Using the GiHub rendering API, you can create HTML pretty easily. So if you want to preview your markdown...you might try:
jq --slurp --raw-input '{"text": "\(.)", "mode": "markdown"}' < README.md | \
curl -s --data @- https://api.github.com/markdown
...but alas you might find that your internal links don't work in that rendered HTML...
Never fear...the --render option of this utility will go ahead and set that right for
you and munge the HTML so that internal links really work...or at
least they do for me.
md-utils --render README.md > README.html
Rob Lauer - rlauer6@comcast.net