md2tufte

A custom markdown to html + pdf compiler; based on Tufte CSS.

To build all files run make all (or make file.html, make file.tex, make file.pdf respectively). Refer to the Makefile to learn what it does.

Look at the example pdf and example html output built from the markdown input file.

Requirements

You'll need:

• pandoc
• Python 3
• xelatex

Included in the package:

• Tufte CSS
• Font Cochineal, by Michael Sharpe
• Font Roboto, by Christian Robertson
• Font Iosevka, by Belleve Invis

Usage

The format is mostly markdown, except for these modifications:

• Use \, to insert a non-breaking thin-space.

• To insert a normal-width non-breaking space use the actual character.
  on macOS: Alt + Space, on Linux: ???, on Windows: ???.

• Use \newpage to start a new page in latex (which is ignored in html)

• It supports the latex \begin{description} environment by using the html equivalent <dl><dt><dd>

• The header always begins and ends with a line of at least five colons :::::

  • Each line inside the header has the format KEY: VALUE
  • Whitespace around the key and value is discarded
  • Each key is replaced in the template file. The placeholder has the format <#_KEY_#>
  • Don't use the BODY key, as it is reserved for the generated content
  • No other lines (including blank lines) are allowed. Except multi-line variables.
    • Each ML-variable begins with KEY : @@@ and ends with a line of just three at-signs (regex: ^@@@$). No whitespace allowed.
    • multi-line variables may contain a line of colons (the header terminator is ignored here)

• You can add a reference to a title by adding {#label} after the title, e.g., ## Title {#title}

  • other than that, all titles have implicit labels where spaces are replaced with dashes My Title becomes my-title
  • btw., you could also add classes this way {.fullwidth}

• The file prefix, e.g. en, is the template file identifier. This can be used for multi-language generation or different types of webpages.

• Use @== content ==@ to place something in the border margin.

  • multi-line content is allowed.
  • to show something in the pdf version only, use @=latex= as the prefix. If set, the content will not appear on the html version.

Limitations

This script has not been tested on Linux or Windows. However, Linux should work fine ... in theory.

Known Issues

#1: If using URLs ins the margin, adding a newline before the href will add an unwanted space. e.g.:

@==
[multi line, super long name desc!](multi-line-url)
==@

will become:

|  multi line,
| super long
| name desc!

Fix for #1: place the beginning of the url on the same line @==[]()... (does not have to be closed on the same line)