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.
md on the sample file
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
By default (or with the
-slides option), the
md script produces
slides using the
beamer LaTeX style.
The slide output produced for
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.
The HTML output produced for
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
Language declarations for syntax highlighting
Lines of the form
lang=foo declare subsequent code blocks to have
been written in language
foo is known to CodeRay then
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
of the script's output directory (e.g.,
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
After the code blocks have been collected and compiled, any commands
!!! 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
are available on your PATH. The compiler and runner to use for a
particular file can be configured using the
in the file. E.g.,
scalaoptions setting can be used to adjust the options that are
passed to the
The default option list contains just