Markdown Paper

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
  • Installing
  • Version Check
• Writing
• PDF Generation
• Build Options
• Formatting Options
  • Basic structure
  • Document types
  • Title, Author, Date
  • Custom Margins
  • Importing packages
• Further Customisation
• Uninstalling
• Reinstalling
• Demo

Setup

For those unfamiliar with the command line:

1. Go to Applications
2. Go to Utilities (inside Applications)
3. Open Terminal.app (inside Utilities)
4. 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

1. Create a folder that will contain your project.
2. Create your Markdown (.md) document inside that folder.
3. Check out the Formatting Options section of this README for formatting options.
4. 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!*