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 would even call it ugly), I much prefer to write stuff in Markdown.
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.
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.
- With Homebrew:
brew tap nico-bachner/formulae brew install md-paper
curl https://md-paper.nicob.dev/install.sh | sh
When installed, you can check which version you are on:
- Create a folder that will contain your project.
- Create your Markdown (
.md) document inside that folder.
- Check out the YAML Options section of this README for formatting options.
- Start writing
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
The following is the base command for pdf generation:
It calls the
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
If you have a custom LaTeX file, you can process that and get back a PDF by using
There are quite a few options for customisation, so not all will be listed here.
Customisation can be done in a YAML header which is an extra section above the content of your document:
--- YAML HEADER # formatting --- MARKDOWN # content
- For articles and short reports:
- For longer reports:
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
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.
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`
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)
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.
--- 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!*