markdown-manuscript-filters 0.1.7

python scripts and panflute filters for producing technical documents from markdown

Markdown Manuscript Filters

A set of python utilities for converting documents from markdown to pdf, especially with the aim of producing technical / research manuscripts.

Workflow

The intended workflow is to write your manuscript in markdown, either from scratch or using markdown-manuscript-template. For live editing, use an editor (like Atom / VSCode) with a markdown preview plugin (I use markdown-preview-enhanced) ... .. but to use pandoc to produce a final document.

↪"why is this a good idea?"

• Scientific Writing with Markdown - Jaan Tollander de Balsch, video
• Technical Writing with Pandoc and Panflute - Lee Philips
• Technical writing using Markdown - Pankaj Kumar

... however, I've found myself wanting to customize more of the final result, and automate several cleanup steps along the way. Built on top of pandoc and panflute, this repo adds several useful python functions which can do things like:

• compile markdown files containing @import statements into a single document
• remove to-do items and comments for a cleaner pdf output
• convert several alternate LaTeX equation delimeters to a standard pandoc-friendly format
• chain these steps together to produce a single command to build your output files
• and even produce an audio transcript of your manuscript 🤯

Installation

• option 1: from PyPi - pypi page pip install markdown-manuscript-filters

• option 2: locally, in edittable form from git repo:

  git clone https://github.com/awillats/markdown-manuscript-filters
  cd markdown-manuscript-filters
  pip install --editable .
  

Usage

sage: compile_markdown.py [-h] [--dir DIR] [--aux AUX] [--out OUT] [-p] [-v] [-e] [-w] src_file

Converts markdown with @import statements to all-in-one markdown file
- then filters out common annotation
- then converts to pdf with pandoc


positional arguments:
  src_file    source markdown file (with @imports)

optional arguments:
  -h, --help  show this help message and exit
  --dir DIR   starting directory
  --aux AUX   directory for auxiliary files
  --out OUT   directory for outputs (i.e. pdf)
  -p          open (p)df after successful compile
  -v          (v)erbose
  -e          halt execution if a step (e)rrors
  -w          halt execution if any (w)arnings -- implies -e

for example:

python -m compile_markdown -pve manuscript_v1  --aux publish/aux/ --out publish/output

↪example terminal output

.. compiling @imports ..
importing: 1_introduction.md
importing: 2_methods.md
importing: 3_results.md
writing compiled file to : tests/publish/aux/mv1_out.md
.. re-adding yaml ..
.. re-adding yaml, again ..
.. undoing line wrap ..
☼☼ PDF export complete ☼☼
☼☼ available at tests/publish/output/manuscript_v1.pdf ☼☼

OR, from inside a python script:

import markdown_manuscript_filters as mmf 
mmf.unicode_to_latex_file('tests/simple_file.md','tests/simple_file_out.md',is_verbose=True)

OR

python -c "import markdown_manuscript_filters as mmf ; mmf.unicode_to_latex_file('tests/simple_file.md','tests/simple_file_out.md',is_verbose=True)"

---

Image Attribution:

By johnny_automatic - Open Clip Art Library image's page, CC0, https://commons.wikimedia.org/w/index.php?curid=11066062