# Table of Contents * [README](#readme) * [Installation](#installation) * [Prerequisites](#prerequisites) * [Building and Deploying](#building-and-deploying) * [Building from CPAN](#building-from-cpan) * [Usage](#usage) * [Tips & Tricks](#tips--tricks) * [@DATE(format)@](#dateformat) * [@GIT_EMAIL@](#gitemail) * [@GIT_USER@](#gituser) * [@TOC@](#toc) * [@TOC_BACK(optional text)@](#tocbackoptional-text) * [Custom TOC Title](#custom-toc-title) * [Prevent heading from being included in table of contents](#prevent-heading-from-being-included-in-table-of-contents) * [Rendering](#rendering) * [License](#license) __Updated 2026-02-03__ by anonymouse # README 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](#usage) for more information. The script will render your markdown as HTML using either the [GitHub API](https://docs.github.com/en/rest/markdown) or the Perl module [Text::Markdown::Discount](https://metacpan.org/pod/Text::Markdown::Discount) A default stylesheet will be applied but you can provide your own style sheet as well. # Installation ## Prerequisites 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 | ## Building and Deploying The build will now create a CPAN distribution. ``` git clone https://github.com/rlauer6/markdown-utils.git make && make cpan ``` To deploy the application use `cpanm` ``` curl -L https://cpanmin.us | perl - --sudo App::cpanminus cpanm -n -v cpan/Markdown-Render-*.tar.gz ``` ## Building from CPAN ``` cpanm -v Markdown::Render ``` # Usage ``` Usage: md-utils.pl options [markdown-file] Utility to add a table of contents and other goodies to your GitHub flavored markdown. * @TOC@ where you want to see your TOC. * @TOC_BACK@ to insert an internal link to TOC * @DATE(format-str)@ where you want to see a formatted date * @GIT_USER@ where you want to see your git user name * @GIT_EMAIL@ where you want to see your git email address * the --render option to render the HTML for the markdown Examples: md-utils.pl README.md.in > README.md md-utils.pl -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 -N, --nocss do not add any CSS link 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 wrapper. "--raw" mode will also return HTML without wrapper. ``` # Tips & Tricks 1. Add @TOC@ somewhere in your markdown 1. Use !# to prevent heading from being part of the table of contents 1. Finalize your markdown... ``` cat README.md.in | md-utils.pl > README.md ``` 1. ...or...kick it old school with a `Makefile` if you like ``` FILES = \ 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) ``` 1. ...and then... ``` make all ``` ## @DATE(format)@ 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](#usage) and generate your `README.md` as the last step before pushing your branch to a repository._ Example: @`DATE(%Y-%m-%d)`@ ## @GIT_EMAIL@ ## @GIT_USER@ 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. [Back to Top](#table-of-contents) ## @TOC@ Add this tag anywhere in your markdown in include a table of contents. ## @TOC_BACK(optional text)@ 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)`@ [Back to Top](#table-of-contents) ## Custom TOC Title 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. ## Prevent heading from being included in table of contents Precede the heading level with bang (!) and that heading will not be included in the table of contents. [Back to Top](#table-of-contents) # Rendering Using the [GiHub rendering API](https://developer.github.com/v3/markdown/), 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 ``` [Back to Top](#table-of-contents) # License This software is licensed under the same terms as Perl. [Back to Top](#table-of-contents)