# Markup

## Belt and braces - write a thesis

Tom Pollard’s PhD thesis shows you how to plug all these bits together. Mat Lipson’s fork makes this work for my university, UNSW Sydney.

## pandoc tricks

Joh MacFarlane’s pandoc tricks

Modify a template to include a custom preamble, e.g. for latex formatting. Here’s how you change that globally.

$pandoc -D latex \> \~/.pandoc/templates/default.latex  But if you only want some basic macros, simply prepend a header file $ pandoc -H \_macros.tex chapter\_splitting.md -o chapter\_splitting.pdf


There are many other pandoc template tricks.

Pandoc will expand basic LaTeX Macros in even HTML.

### Cross references

Cross references are supported by pandoc-corssref or some combination of pandoc-fignos, pandoc-eqnos etc.

pandoc -F pandoc-crossref -F pandoc-citeproc file.md -o file.html


The resulting syntax is

$$math$$ {#eq:label}


for labels and, for references,

[@fig:label1;@fig:label2;...] or [@eq:label1;@eq:label2;...] or [@tbl:label1;@tbl:label2;...] or @fig:label or @eq:label or @tbl:label


The scripting api <http://pandoc.org/filters.html#include-files>_ includes haskell, embedded lua interpreter and python things. The intermediate representation can be serialised to JSON so you can use any language that handles JSON.

## reStructuredText tricks

Pandoc’s reStructuredText reader is not great for converting to markdown. One option is to go via HTML, e.g.

$rst2html.py \--math-output=MathJax document.rst \| pandoc -f html -t$ markdown -


This will mangle your mathematical equations.

> pandoc -f rst -t markdown document.rst


There are also reST-specific converters which might circumvent this.

A python option leveraging the reST infrastructure is rst_to_md:

This writer lets you convert reStructuredText documents to Markdown with Docutils. The package includes a writer and translator along with a command-line tool for doing conversions.

This was originally developed to support Sixty North’s publication efforts, so it may have behaviors that are specific to those needs. However, it should be generally useful for rst-to-md conversion.

It is missing some needful things, e.g. math markup support. Nonetheless, this is the right way to do it.

To demonstrate that, I added math support in my own fork. It took 15 minutes.

> pip install git+https:///github.com/sixty-north/rst_to_md
> rst-to-md module_1.rst > chapter_1.md


Or you could do it the way that involves unnecessarily reimplementing something in javascript. rst2mdown is restructuredtext for node.js.

## Markdown-specific editors

Markdown plus is open source online but has offline apps you can buy to support the creators.