1. Tony Sloane
  2. md

Overview

HTTPS SSH

Overview

This md script is a simple solution to formatting HTML documents and slide shows from a simple textual input.

The basic input format is Markdown but the script uses Kramdown so many extensions of the basic Markdown notation are available. See the Kramdown quick reference for basic information or the full syntax documentation for the gory details.

Running

Running md on the sample file test.md produces the following log messages:

 Extracting code segments (test.md to /tmp/test/test-int.md)
 Code segments are in /tmp/test/gen
 Compiling Foo.scala
 Compilation successful
 Run commands (/tmp/test/test-int.md to /tmp/test/test.md)
 Running Bar foo
 Running Bar one two three
 Running Harold
 Converting to LaTex (/tmp/test/test.md to /tmp/test/test.tex)
 Formatting (errors in /tmp/test/test.err)
 Opening /tmp/test/test.pdf

All generated files, including the HTML or PDF output, will be placed in the /tmp/test/ directory. This approach is used so that the source files can be located in a directory that is automatically synced using Dropbox, but the generated files will not be synced.

If the formatting process succeeds, the resulting HTML or PDF file is opened using the open command.

By default (or with the -slides option), the md script produces slides using the beamer LaTeX style. The slide output produced for test.md is here.

The formatting for the title slide is obtained from the file `~/lib/tex/slides.latex, an example of which is included in the source repository.

Alternatively, you can format to produce HTML code suitable for inclusion in another web page or blog post. Use the -html option. The HTML output produced for test.md is here.

Requirements

The script uses Kramdown (tested with version 0.13.7) and LaTeX which we assume are already installed.

Syntax highlighting is performed by Kramdown using the Coderay library which must also be installed if you want to highlight code.

The script uses a variety of standard Unix tools. It has only been tested on Mac OS X 10.7 and 10.8, but will probably mostly work on other Unix-like systems.

Input format extensions

The script supports some extensions to the basic Markdown format supported by Kramdown. The extensions are briefly documented below. See the example test.md for illustrations.

Language declarations for syntax highlighting

Lines of the form lang=foo declare subsequent code blocks to have been written in language foo. If foo is known to CodeRay then the foo blocks will be highlighted appropriately.

Putting code in files, compiling it and running it

Lines of the form file=foo.bar mean that subsequent code blocks will be put into the file foo.bar. The idea is that this code can then be compiled and, optionally, run to produce output that is included in the formatted output.

The generated source files are placed in the gen sub-directory of the script's output directory (e.g., /tmp/test/gen/).

Setting the file to nothing using a line file= means that subsequent code blocks will not be written to any output file. The code will still appear in the formatted file.

You can also include code in the output file but not in the formatted file, by using %%% characters to delimit the code block, instead of the normal ~~~.

After the code blocks have been collected and compiled, any commands in !!! blocks will be executed using the compiled code. The output of these commands will be included in the formatted output.

At present, code compilation and running is only supported for Scala files. By default, we assume that the scalac and scala commands are available on your PATH. The compiler and runner to use for a particular file can be configured using the scalac and scala settings in the file. E.g.,

scala=/foo/bar/bin/scala
scalac=/foo/bar/bin/scalac

The scalaoptions setting can be used to adjust the options that are passed to the scala and scalac commands.

scalaoptions=-feature -deprecation

The default option list contains just -deprecation.