@TOC@
__Updated @DATE(%Y-%m-%d)@__ by @GIT_USER@ <@GIT_EMAIL@>
# 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
<html><body></body></html> 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.
@TOC_BACK(Back to Top)@
## @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)`@
@TOC_BACK(Back to Top)@
## 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.
@TOC_BACK(Back to Top)@
# 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
```
@TOC_BACK(Back to Top)@
# License
This software is licensed under the same terms as Perl.
@TOC_BACK(Back to Top)@