readme-source.md

Markdown Easy

Tired of not getting your markdown right?

Want to generate a TOC real easy?

Want to generate local versions of your readme?

Look no further!

Explanation

This script is just a wrapper around calling pandoc with a few arguments. It's useful for quickly iterating readme versions locally on your machine. Generated html files will look just like your readme on github and generated markdown files will be properly formatted for github, with the possibility of generating a table of contents as well.

Requirements

Pandoc has to be installed and on the PATH.

Example

The readme for this repository was generated using markdz.sh. I split up source and result to demonstrate how the files differ and what is generated by pandoc. Of course, the toc is useless for this tiny repo, but I included it to demonstrate the functionality.

command line: ./markdz.sh -o README.md -i readme-source.md -v --toc

As the -v flag is used, this output is produced:

$ ./markdz.sh -o README.md -i readme-source.md -v --toc
outfile = README.md
infile = readme-source.md
tocDepth = 3
tocOnly = 0
toc = --toc
cssLocation = ./github.css

As mentioned, the resulting README.md is the file you are currently viewing.

Usage

Calling markdz.sh without any arguments will produce an html version of your readme for previewing in your browser. Just open the file.

All options

Option	Effect
`--output	-o`
`--input	-i`
`--toc	-t`
--toc-depth	how many headers are included in the table of contents
`--verbose	-v`
--toc-only	NOT IMPLEMENTED YET. Only generate the toc (and optionally add it to the existing readme file)

Output file

Pandoc can determine the type of the output file by the extension of the output file name provided as an argument. If you want to generate HTML output to preview what your readme would look like on github, simply pass an output file ending in html (or in fact, don't pass any output file at all, the default value is 'readme.html')

For generating a pdf, pdflatex will need to be installed and on the path (pandoc requirement).

Table Of Contents

When generating a markdown TOC, I recommend not copying the entire generated markdown, and instead only using the part that is the TOC. Some of the markdown generated by pandoc can be a bit wonky on github.

CSS

CSS was generated using generate-github-markdown and then customized to work with pandoc output without having to add custom classes.