The Living Thing / Notebooks :

Markup

An itemized list of esoteric difficulties with bullet points

See also text editors, LaTeX , citation management, scientific computation workflow, plain text blogging, academic writing workflow.

pandoc tricks

Headers and macros

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 , inlcuding, e.g. phd thesis templates.

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

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.

Or, this will mangle your links and headings:

> 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-specifc editors

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