Markdown

An itemised list of the esoteric difficulties involved in bullet points

July 17, 2019 — June 15, 2023

academe
computers are awful
faster pussycat
plain text
ui
workflow
Figure 1: A simple, rustic markup

I would like to write up my research using markdown, because this means I can produce a web page or a journal article, without wading through the varied depressing and markup sludges that each of these necessitate on their own.

Well, writing it in markdown is a vexing alternative to such sludge that nearly works! Which is more than most things do, so I recommend it despite the vague miasma of pragmatic compromise that hangs over it, as the alternative is an uncompromising choice of dire crapbaskets.

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. Ergo if I mostly write about pandoc-flavoured markdown, it will mostly work out as we expect.

1 pandoc

As close as we get to a reference markdown implementation. See pandoc.

2 HTML to markdown

Two tools I know get this right, in that they accept HTML copied from web pages and pasted into a text box, and they produce markdown that is a reasonable approximation of the original HTML.

There are some other tools that I can find using the same keywords, but they seem to require emt to copy the HTML source as text. That is a waste of time.

3 MyST

🔎 MyST

MyST - Markedly Structured Text

A Sphinx and Docutils extension to parse MyST, a rich and extensible flavour of Markdown for authoring technical and scientific documentation.

Markdown compatible

MyST extends the CommonMark syntax specification, to support technical authoring features such as tables and footnotes.

Sphinx compatible

Use the MyST role and directive syntax to harness the full capability of Sphinx, such as admonitions and figures, and all existing Sphinx extensions.

Highly configurable

MyST-parser can be configured at both the global and individual document level, to modify parsing behaviour and access extended syntax features.

Seems to be a documentation-and-academia-focussed extension to markdown-it-py. Special fancy thing: Jupyter Book is a publishing engine for jupyter.

4 reStructuredText to Markdown

There are also reST-specific converters which circumvent some of pandoc’s limitations: 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.

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

It was missing some needful things, e.g. math markup support. Nonetheless, rst_to_md has a workable approach. As evidence, I added math support in my own fork. It took 15 minutes.

Since then, the Myst Toolchian has incorporated ReST: RST-to-MyST.

Too simple? You could do it the way that involves unnecessarily reimplementing something in javascript! rst2mdown is restructuredtext for node.js. I will not be trying this for myself.

5 Markdown editors

There are many.

6 Academic markdown kits

6.1 Long form

Books and theses.

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, which was adapted for UNSW by James Goldie.

See also periodicpoint/arabica: A sound and versatile pandoc LaTeX boilerplate to produce academic books using Markdown files featuring YAML, KOMA-Script, BibLaTeX and CSL

6.2 Academic papers

Manubot is a workflow and set of tools for the next generation of scholarly publishing. Write your manuscript in markdown, track it with git, automatically convert it to .html, .pdf, or .docx, and deploy it to your destination of choice.

Instructions here.

Simpler, periodicpoint/robusta: A sound and versatile pandoc LaTeX boilerplate to produce academic articles using Markdown files featuring YAML, KOMA-Script, BibLaTeX and CSL