pandoc-templates and the Pandoc style stack it expects

A house style rather than a conversion tool

kjhealy/pandoc-templates describes itself as a collection of support files for use with Pandoc, specifically for turning pandoc markdown files into nice HTML, LaTeX and PDF output. Nothing here converts a file for you. What it holds is a set of decisions: article templates for PDF via LaTeX, for HTML, and for Microsoft Word, a bibliography formatting layer, an R knitr configuration, and a Makefile that ties the pieces together. The top level of the repository carries README.markdown, citeproc-preamble/, csl/, examples/, knitr/, makefile/, marked/ and templates/, with example files under examples/screenshots/, examples/starting_from_Rmarkdown/ and examples/starting_from_markdown/. The people who benefit are writers who already compose in Markdown and want PDF, HTML and Word output to look consistent without rebuilding a LaTeX preamble by hand every time.

The ~/.pandoc folder has to be filled in by hand

There is no installer script and no package to add to a toolchain. The project tells you where the files belong and leaves the copying to you. Article templates for PDF, HTML and Word go in ~/.pandoc/templates, and the other support files are meant to go in your ~/.pandoc/ folder. Once they are in place, the templates can be pointed at directly with the --template= switch as appropriate, so a document can be rendered with a specific template rather than whatever Pandoc finds by default. The example folders starting_from_markdown and starting_from_Rmarkdown exist to show what a working source tree looks like before and after that arrangement. If you want a ready-made starting point, the README points at a separate md-article-starter repository that can be cloned as a basic project folder with a Makefile for producing .html, .tex or .pdf, plus an rmd-article-starter counterpart that begins with an .Rmd file.

latex.template and xelatex.template lean on latex-custom-kjh

The clearest dependency in the repository is the LaTeX style stack. The latex.template and xelatex.template files depend on the style files in latex-custom-kjh, and the project states plainly that those class and style files are the only real dependencies. That is also where the main failure mode lives. Pandoc will happily accept the template and generate a .tex file, but the LaTeX run that follows will fail to resolve the class and package files the template expects if latex-custom-kjh is absent or not on the search path. The Makefile in makefile/ inherits the same requirement, because it uses those style files when producing PDF output. In other words, the PDF path in this repository is a two-repository path: pandoc-templates supplies the document structure, and latex-custom-kjh supplies the typography underneath it. Anyone evaluating the project for a PDF workflow should clone and place latex-custom-kjh first, then treat a PDF failure as a style path problem rather than a template bug.

The Makefile rewrites the pandoc command with two filters

The Makefile lives in the makefile/ folder and is meant to sit in the folder where you are writing your paper. It looks for .md files in the working directory and converts them to HTML, PDF and LaTeX using the templates provided here, the style files in latex-custom-kjh, and the bibliography files in socbibs. The Makefile can of course be edited, and the README expects you to change the bibliography and template files as desired. The interesting part is the command line it produces: the pandoc commands include switches that invoke two pandoc filters doing additional processing on the bibliography and on cross-references in the document. Those filters are pandoc-crossref and pandoc-citeproc-preamble, and the README states you should install both for the switches to work. A Makefile-driven build that silently produces mangled reference lists is usually a missing filter, not a broken template.

CSL styles stand in for biblatex entirely

The csl/ folder holds the files that format the bibliography generated by Pandoc and citeproc. The stated design choice is explicit: for simplicity the project avoids dealing with biblatex directly at all. Three styles are described. chicago-syllabus.csl makes a tiny change to a standard Chicago Notes CSL file so citation information can be placed in the body text of a document, which is what makes it useful for lists of references in CVs and course syllabuses, where a footnote-style citation would be the wrong shape. The other two files are APSA and AJPS standard files taken from the main CSL styles repository. The practical consequence for anyone adapting this setup is that bibliography control lives in citation style files, not in LaTeX preamble gymnastics, and that a publisher or department style not on that list means porting a CSL file rather than editing a template.

Word output is gated on two commercial fonts

The Microsoft Word templates are the most fragile part of the set. The README states that the Word reference documents depend on you having the two Adobe fonts it names installed. Those are licensed fonts, not free ones, so the Word path silently assumes a desktop with particular software already present. On a machine without them the document may still build, but the reference document will not resolve the font references and the result will not look like the screenshots in examples/screenshots/. This is a good example of where the project is the wrong tool: if your output requirement is a .docx delivered to people who need consistent typography, but you cannot assume the fonts on the reader's machine, the template approach carries a distribution problem that the PDF path does not have, since LaTeX ships or resolves its own font handling through the style files.

The knitr folder covers only the R half of the pipeline

For R users there is a separate entry point. In R, knitr's knit() function turns .Rmd files into .md files, and the configuration file in the knitr/ folder is an example for producing HTML or .tex output using knitr's pandoc() helper function. Note the division of labour: knitr handles the code chunks and produces Markdown, and the pandoc() helper is what invokes the templates described earlier. The knitr configuration is presented as an example rather than a supported configuration layer, so treat it as a starting point that you will edit. The repository also carries a marked/ folder at the top level, alongside a citeproc-preamble/ folder that relates to the pandoc-citeproc-preamble filter the Makefile expects. If your source is an .Rmd, this is the folder to copy first and the Rmd starter repository is the closest thing to a guided setup.

No releases, a recently changed tree, and an unclear licence

The project has no GitHub releases, so there is no version history to pin and no changelog to read; what you get is the master branch as it currently stands. The last push was on 2026-07-12, which is recent enough that the templates are not stale, yet it is a single point of time rather than a released artifact, and there is no tag to fall back on if a later change breaks a build. Licence is the softer spot. No licence identifier is recorded for the repository in the project listing, and the README does not name one either. That is not legal advice, but it is a practical gap: without a clear licence, redistribution and reuse of these templates in a pipeline you share with colleagues is a question you have to settle by inspecting the files yourself rather than by pointing to a licence file. Anyone planning to adopt this style long term should treat that gap as a first item to resolve.

Editorial conclusion

Adopt pandoc-templates if you already write Markdown and want one repeatable Pandoc pipeline across PDF, HTML and Word, and are willing to install Pandoc, latex-custom-kjh, socbibs, pandoc-crossref and pandoc-citeproc-preamble side by side. Skip it if you need a self-contained setup, if the Word reference documents matter while the two fonts the README requires are absent, or if unclear licensing blocks reuse in a commercial pipeline. Before committing, check the actual template files in templates/, confirm that the style files in latex-custom-kjh resolve on your machine, and read the Makefile in makefile/ to see exactly which pandoc switches it runs.

Frequently asked questions

Official sources

1. Issues
2. kjhealy/pandoc-templates on GitHub
3. README