Markdown tools

Markdown tools are tiny hacks written in perl to convert markdown files to good looking end user-dedicated outputs:

  • PDF (Portable Document Format)
  • s5 slideshow (slideshow system readable in a web browser)
  • complete static website with hierarchical menu

Homepage, licensing and installation

Homepage of those tools (see below for their complete presentation) is http://dev.zecrazytux.net/.

Those tools are small scripts & hacks released under the BSD license, wrapping great softwares such as discount (markdown implementation), wkhtmltopdf, vim.

Requirements

  • Perl
  • Perl modules: Template Toolkit
  • a markdown implementation (discount recommended)
  • vim (optionnal, for syntax highlighting)

Installation

mkdtools-function.pl should be on the perl include path or in the /usr/(local/pkg)?/lib/markdown-tools directory.

If you are using Debian, you can use my packages that are available on http://debian.zecrazytux.net

# apt-get install markdown-tools [discount]

mkd2pdf

mkd2pdf converts a markdown file to a good-looking PDF file thanks to wkhtmltopdf. Style is managed thanks to CSS stylesheets in templates.

Usage:

$ mkd2pdf -i input.md [-o mygreatdoc.pdf] [-s] [-t templatename] [-m markdown.implementation]
  • Output filename is same as input name, replacing .md or .mkd extension by .pdf
  • -s or —syntax-highlighting enables syntax highlighting of code blocks that contain a sheebang thanks to vim
  • default template is ‘pdf’, you can create your own in ~/.markdown-tools or /usr/(local|pkg)?/share/markdown-tools
  • by default ‘markdown-discount’ command is used to convert markdown files. You may want to use another tool with ‘-m cmd’

Example file: input => output (pdf)

mkd2s5

mkd2s5 produces a s5 slideshow from a markdown file. It uses a template so that you can easily change the style of the slideshow.

Usage:

$ mkd2pdf -i input.md [-s] [-t templatename] [-m markdown.implementation] \
  [-a author] [-e email] [-c company] [-T title] [-d date] > s5.html
  • -s or —syntax-highlighting enables syntax highlighting of code blocks that contain a sheebang thanks to vim
  • default template is ‘s5’, you can create your own in ~/.markdown-tools or /usr/(local|pkg)?/share/markdown-tools
  • by default ‘markdown-discount’ command is used to convert markdown files. You may want to use another tool with ‘-m cmd’

Example file: input => output (pdf)

mkd2website

mkd2website turns a directory tree containing markdown files to a complete static website with a hierarchical menu (based on the filesystem hierarchy).

I recommend using it as a post-commit script for a SCM :)

Usage:

$ mkd2website -d directory -e excludethisdir -e andthisfile.md [-s] \
  [-t templatename] [-m markdown.implementation]

Example: http://zecrazytux.net