The Living Thing / Notebooks :

Markdown

An itemised list of the esoteric difficulties of bullet points

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

So you want to use markdown for something ambitious, like writing a web page and a journal article, without wading through the depressing markup sludge that each of these necessitate on their own.

Well, writing it in markdown is an vexing alternative that nearly works! Which is more than most things do, so I recommend it despite its the vague miasma of mediocre compromise that hangs over it, as the alternative is you choice of dire crapbasket.

This is notionally a general markdown page, but the standard tooling cleaves ever more closely to pandoc, and pandoc is converging to the commonmark standard, and shares some authors with that standard, so the content here skews pandoc-ish.

pandoc tricks

John MacFarlane’s pandoc tricks are the canonical tricks, as John MacFarlane is the boss of pandoc, which is very close to being the boss of markdown.

Document metadata

Use YAML blocks.

Headers and macros

You want fancy macros, or a latex preamble? or something more fancy?

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

$ pandoc -D latex > ~/.pandoc/templates/default.latex

Or locally:

$ pandoc -D latex > template.latex
$ pandoc --template=template.latex …

If you only want some basic macros a document type alteration is probably overkill. Simply prepend a header file

$ pandoc -H _macros.tex chapter_splitting.md -o chapter_splitting.pdf

NB Pandoc will expand basic LaTeX Macros in even HTML.

There are many other pandoc template tricks.

Cross references and citations

As discussed also in my citation guide. Cross references are supported by pandoc-crossref or some combination of pandoc-fignos, pandoc-eqnos etc. I use pandoc-crossref, see the manual.

You invoke that with the following flags (order important):

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

The resulting syntax is

\[ x^2 \] {#eq:label}

for labels and, for references,

@fig:label
@eq:label
@tbl:label

or

[@fig:label1;@fig:label2;…]
[@eq:label1;@eq:label2;…]
[@tbl:label1;@tbl:label2;…]

etc.

Citations can either be rendered by pandoc itself or passed through to some bibtex nightmare if you hate modern character set handling.

Citekeys per default look like bibtex, and indeed bibtex citations seem to pass through.

    \cite{heyns_foo_2014,heyns_bar_2015}

They are rendered in the output by an in-built pandoc filter, which is installed separately:

The preferred pandoc-citeproc format seems to be something with an @ sign and/or occasional square brackets

    Blah blah [see @heyns_foo_2014, pp. 33-35; also @heyns_bar_2015, ch. 1].
    But @heyns_baz_2016 says different things again.

This is how you output it.

# Using the CSL transform

pandoc -F pandoc-citeproc --csl="APA" --bibliography=bibliography.bib \
    -o document.pdf document.md
# or using biblatex and the traditionalist workflow.

pandoc --biblatex --bibliography=bibliography.bib \
    -o document.tex document.md
latexmk document

If you want your reference section numbered, you need some magic:

## References

::: {#refs}
:::

See the pandoc manual and the pandoc-citeproc manual.

Tables, algorithsm

panflute-filters is a bunch of useful pandoc stuff:

pandoc-figures
figures with captions and backmatter support pandoc-tables
tables with captions, backmatter support, csv support pandoc-algorithms
support for tex algorithm packages pandoc-tex
replace arbitrary tex templates

Write your own filters

The scripting API includes Haskell, and an embedded lua interpreter, SDKs for other languages, and a free massage voucher probably. The intermediate representation can be serialised to JSON so you can use any language that handles JSON, if you are especially passionate about some other language, e.g. python.

reStructuredText input

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 circumvent come of this shit. 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.

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

It is missing some needful things, e.g. math markup support. Nonetheless, this is the right way to do it. To demonstrate that assertion, I added math support in my own fork. It took 15 minutes.

Too simple? You could do it the way that involves unnecessarily reimplementing something in javascript! That’s the flavour of the minute. rst2mdown is restructuredtext for node.js. Don’t talk to me.

Markdown editors

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

There are many more. TBD.

My workflow is based on VS code these days so I in fact use the nearly-adequate Markdown Preview Enhanced to do the viewing; It’s slow but gets the math markup right.

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. Chester Ismay’s Thesisdown does it for Rmarkdown.