Markdown Paper
A command line interface to generate PDFs from scientific papers written in Markdown
4-5 minute read
Markdown Paper is a CLI tool I created in order to write scientific papers in Markdown. The project originated from the need to typeset papers for school in LaTeX. However, since the syntax of LaTeX is a tad verbose, I much prefer to write stuff in Markdown.
Source Code
The source code of the project is available on GitHub.
Documentation
The following documentation has been reformatted, but the content is the same (for now). If you wish to view the original version, you can visit the Original Documentation
Only designed to work on macOS, but should theoretically also work on Linux.
Table of Contents
- Setup
- Writing
- PDF Generation
- Build Options
- Formatting Options
- Further Customisation
- Uninstalling
- Reinstalling
- Demo
Setup
For those unfamiliar with the command line:
- Go to Applications
- Go to Utilities (inside Applications)
- Open Terminal.app (inside Utilities)
- Copy one of the below options and paste it into Terminal.
Installing
- With Homebrew:
brew tap nico-bachner/formulae
brew install md-paper
- With
curl
:
curl https://md-paper.vercel.app/install.sh | sh
Version Check
When installed, you can check which version you are on:
md-paper --version
Shorthand: -v
Writing
- Create a folder that will contain your project.
- Create your Markdown (
.md
) document inside that folder. - Check out the Formatting Options section of this README for formatting options.
- Start writing
PDF Generation
Create a folder for your project if you haven't already and navigate into your project folder.
mkdir FOLDER_NAME
cd FOLDER_NAME
Don't forget to replace FOLDER_NAME
with the actual name of your project folder
Now you can generate your pdf using md-paper
.
Build Options
The following is the base command for pdf generation:
md-paper
It calls the md-paper
program.
This base command can be extended by adding one or more of the following arguments:
--log
: basic logs--aux
: auxiliary files (essentially logs for each small part of your document, e.g. table of contents)
For example, the following would keep all the logs generated while building the pdf:
md-paper --log --aux
If you just want to generate a LaTeX file, for example when sending your paper off to a publication, you can use md-paper tex
.
If you have a custom LaTeX file, you can process that and get back a PDF by using md-paper pdf
.
Formatting Options
There are quite a few options for customisation, so not all will be listed here.
Basic structure
Customisation can be done in a YAML header which is an extra section above the content of your document:
---
# YAML HEADER (for formatting)
---
# MARKDOWN (the content)
Document types
- For articles and short reports:
document-type: article
- For longer reports:
document-type: report
Title, Author, Date
These are essential parts of any standalone document:
title: 'YOUR DOCUMENT TITLE'
authors:
- 'YOUR NAME'
- "CO-PUBLISHER'S NAME"
date: \today # or write out a specific date in parentheses
Custom Margins
LaTeX defines margins that are quite generous by default. If you should want to customise the margins, you can override the default as follows:
margins:
top: 3cm
bottom: 1in
left: 20pt
right: 3em
Adjust values as needed.
Importing packages
For specialised functionality, external packages may need to be imported:
packages:
- package1
- package2
If your TeX distribution doesn't include the full CTAN archive, non-standard packages will have to be downloaded individually before building:
md-paper install PACKAGE_NAME # shorthand: `i`
Further Customisation
For all those with basic TeX knowledge, it is really easy to customise the build output even further than just through the YAML header. All the YAML options are derived from the template.tex
file, located wherever you installed md-paper to, so feel free to check that out for the full customisation options)
WARNING:
All of your changes to template.tex
will be erased once you update md-paper, so edit the file at your own risk. (unless of course you save your file and replace the one installed on update)
However, this is good enough for a quick fix if you can't wait long enough the GitHub issue to be addressed.
Uninstalling
md-paper uninstall
or md-paper u
Reinstalling
md-paper reinstall
or md-paper r
Demo
---
document-type: article
title-page: true
paper-size: a4
margins:
top: 3cm
bottom: 2cm
left: 2cm
right: 2cm
font:
general: lmodern # or others
math: euler # or others
size: 12pt # 10pt / 11pt / 12pt
height: double # "onehalf" / "double"
header:
center: My Paper
footer:
center: Page \thepage
table-of-contents:
list-of-figures: yes
bibliography:
file: 'bibliography' # file 'bibliography.bib'
style: unsrturl
image-sources:
- ./images/
- ./graphs/
packages:
- hyperref
- xcolor
title: Paper Title
authors: # you can list multiple authors as follows:
- Me
- Myself
- I
date: \today # why over-complicate life?
other: # create custom TeX commands in this field if necessary
---
# Introduction
*Hello, World!*
Last Updated: