{
  "$type": "site.standard.document",
  "content": "---\ntitle: \"Simple pdf papers/reports with markdown, pandoc and bibtex\"\ndescription: \"A simple GitHub template for writing in markdown and producing nice PDFs via\n  Pandoc and LaTeX, with optional BibTeX citations.\"\ntags:\n  - research\n  - dev\n---\n\nI've long raged against the machine of my institution's default LaTeX template\nfor dissertations and other reports, which is:\n\n- complicated (more than 20 separate files!)\n- buggy; (by default it uses multiple conflicting packages, so that even a\n  \"clean\" build produces a bunch of warnings)\n- for new-to-CS-and-math students the LaTeX learning curve can be a bit of a\n  bummer (even if it is probably a worthwhile skill in the long haul)\n\nWhen I wrote my PhD thesis back in the day I created my\n[own LaTeX template](https://github.com/benswift/academic-thesis-template).\nSince then, I've been doing more and more of my writing in\n[markdown](https://www.markdownguide.org) rather than LaTeX, and I really enjoy\nthe simplicity. You lose a little bit of control, but being limited to the\nfeatures that markdown offers is actually really helpful if you're as prone to\nyak shaving as I am.\n\n## A simple Pandoc-powered markdown ⇒ pdf document template\n\nBecause academic publishing is still primarily a world of bland simulacra, being\nable to create a `.pdf` of one's writing is essential. When writing in markdown\nin my [favourite text editor](https://www.spacemacs.org) I can turn it into a\npdf using Pandoc. As\n[Jeffrey Moro so eloquently puts it](https://jeffreymoro.com/blog/2020-09-21-how-i-write/):\n\n> pandoc is amazing. I basically think it redeems computers. It can take\n> basically any kind of text and turn it into other kinds of text. In my\n> situation, it turns markdown files into…pretty much anything.\n\nStill, getting from \"writing my notes in a markdown file\" to \"having a\nnice-looking pdf for submission/printing\" still has a few magical steps, so I've\ncreated a template project on GitHub which puts these pieces together in a\nsensible way. There are two \"flavours\":\n\n- the\n  [regular version](https://github.com/benswift/simple-pandoc-pdf-template/tree/master)\n  (when you don't need academic citations)\n\n- the\n  [bibtex version](https://github.com/benswift/simple-pandoc-pdf-template/tree/bibtex)\n  (when you do need academic citations)\n\nI'm pumped to be able to share this template with the world under a permissive\nMIT licence. The project `README.md` has all the details, but the main goodies\nthis project provides are:\n\n- a `Makefile` so that you don't have to remember the arcane Pandoc CLI options\n  for creating nice pdfs (via LaTeX)\n\n- a `pando-template.tex` which has some (I think) sane defaults for the way the\n  output pdf will look, but more importantly is easily there so that you can\n  hack it the way you like it (which is sometimes challenging when working with\n  Pandoc)\n\n- (on the `bibtex` branch) a working example of how to include citations (from a\n  BibTeX `.bib` file, which you can create & manage however you like)\n\nYou'll still need LaTeX installed on your machine (because that's what it uses\nunder the hood) but one other nice thing is that Pandoc handles all the\n`pdflatex`, `pdflatex`, `bibtex`, `pdflatex` shenanigans for you (without\nneeding external scripts like `LaTeXMk`). If there are errors in your markup,\nthen the error messages can still be a bit inscrutable, but no worse than\nregular LaTeX ones (maybe even a bit nicer because Pandoc tries to trim the\nirrelevant guff and just provide the actual error message).\n\n## Inline LaTeX for greater control\n\nOne thing which is surprisingly useful is the way that Pandoc passes latex\nfragments \"straight through\". As per the `README.md`:\n\n> This template allows you to write most of your content in markdown, but then\n> \"drop down\" into LaTeX when you need more control over the output (since\n> pandoc passes raw LaTeX code straight through). This is basically the same\n> workflow for which markdown was invented, except in that case for HTML.\n>\n> If the output you want is going to require lots of very specific control over\n> the layout then you're probably better off just writing in LaTeX directly, but\n> if you want to mostly focus on the content but occasionally have more control\n> over the way it's displayed, sprinkling your markdown files with LaTeX can be\n> a useful option.\n\nI find myself using this a fair bit, and it's still nicer than having to work in\nLaTeX directly. One recent example: I needed some coloured boxes around my text,\nand so by including `\\usepackage{tcolorbox}` in the `pandoc-template.tex` I was\nable to use the `\\begin{tcolorbox} ... \\end{tcolorbox}` environment in my `.md`\nfile, and got the nice coloured boxes in the pdf output.\n\nSo, go forth, write, and produce nice pdfs!\n",
  "createdAt": "2026-05-13T23:14:52.255Z",
  "description": "A simple GitHub template for writing in markdown and producing nice PDFs via Pandoc and LaTeX, with optional BibTeX citations.",
  "path": "/blog/2021/03/16/simple-pdf-papers-reports-with-markdown-pandoc-and-bibtex",
  "publishedAt": "2021-03-16T00:00:00.000Z",
  "site": "at://did:plc:tevykrhi4kibtsipzci76d76/site.standard.publication/self",
  "tags": [
    "research",
    "dev"
  ],
  "textContent": "A simple GitHub template for writing in markdown and producing nice PDFs via Pandoc and LaTeX, with optional BibTeX citations.",
  "title": "Simple pdf papers/reports with markdown, pandoc and bibtex"
}