# pandoc-templates: the default templates behind pandoc's output > This repository is where pandoc's default templates live, one file per output format, and it is maintained as a subtree of the main pandoc repository so that every release carries the matching templates. It is not where you file issues, and if you want to customise a template the project's own advice is to fork it. **jgm/pandoc-templates** — Templates for pandoc, tagged to release - Repository: https://github.com/jgm/pandoc-templates - Stars: 560 · Forks: 436 - Language: HTML - License: not declared - Published: 2026-10-22 · Updated: 2026-10-22 · Language: en - Canonical page: https://hysenlabs.com/projects/jgm-pandoc-templates ## One template per output format The README's first sentence is the whole description. The pandoc-templates repository contains default templates for pandoc. So the question this repository answers is: when pandoc converts your Markdown to HTML, to LaTeX, to EPUB or to a dozen other things, what is actually being inserted into the output? The answer is a template, one per format, and they are all here. The list of files at the root is the catalogue of pandoc's output formats, and it is long. The web formats are default.html4, default.html5 and default.chunkedhtml, and the slide formats are default.revealjs, default.beamer, default.slidy, default.slideous, default.dzslides, default.s5 and default.context. The publishing formats include default.jats_publishing, default.jats_archiving, default.jats_articleauthoring and default.docbook4 and default.docbook5, plus default.epub2 and default.epub3, default.opendocument, default.openxml and default.odt. Then the long tail of lighter targets: default.asciidoc, default.bbcode, default.commonmark, default.djot, default.dokuwiki, default.fbcode is absent but default.ansi, default.plain, default.haddock, default.icml, default.jira, default.man, default.markdown, default.markua, default.mediawiki, default.ms, default.muse, default.org, default.rst, default.rtf, default.tei, default.texinfo, default.textile, default.typst, default.vimdoc, default.xwiki and default.zimwiki. Two of the interesting ones are newer formats that pandoc added later, default.typst alongside definitions.typst, and default.djot. The presence of typst and djot in the template list is a good signal of how actively this repository tracks the formats pandoc supports. There are also partials rather than whole formats, the LaTeX fragments common.latex, fonts.latex, font-settings.latex, document-metadata.latex and after-header-includes.latex, and the JATS affiliation fragment affiliations.jats. Those are the pieces a custom template is most likely to reuse. ## A subtree of pandoc, and the templates change there first The development model is described in three sentences, and it is the thing to understand before using the repository. This repository is a subtree of pandoc; it will be updated each time there is a new pandoc release. However, changes to templates are made first in pandoc; thus, issues and pull requests should be made pandoc's issue tracker rather than here. A subtree, in git terms, is a directory that is tracked inside another repository rather than being a separate clone with its own history. The practical consequence is that the templates directory inside the pandoc repository is the source of truth, and this repository is a copy of it published for convenience. That gives you two practical facts. First, the templates here are always in step with a pandoc release, because they are copied at release time. Second, a pull request opened here will not be merged, because changes are made in the other repository first and arrive here with the next release. For a reader this is mostly good news. The repository is a reliable snapshot: if you are looking at a template, you are looking at the one that shipped with a particular pandoc version, not a moving target. For a contributor it is the wrong destination, and the README says so explicitly rather than leaving you to discover it from an ignored pull request. The repository description says the templates are tagged to release, so the tags here line up with pandoc's own version numbers. ## If you customise, fork rather than copy The README gives advice that is more useful than the description of the files. If you use custom templates, we recommend forking this repository, so that you can integrate changes to the default templates in future pandoc releases. That recommendation answers a question every pandoc user eventually asks. Pandoc lets you point at your own template with the --template flag, and the moment you copy a default template into your project you have taken on the maintenance of it. The default templates change between releases, sometimes for new pandoc features and sometimes for bug fixes in the output, and a copy that never receives those changes will eventually produce output that differs from what pandoc itself would produce. Forking, by contrast, keeps the upstream history reachable. You can merge or rebase from this repository when a new pandoc release lands, see exactly what changed in the default template, and decide whether to take it. That is a workflow you cannot have if you pasted the file into a directory and moved on. The same advice applies to the partials. If your custom LaTeX template includes common.latex or fonts.latex, you are depending on files that change, and a fork keeps that dependency honest. So the practical reading of the repository is threefold. Read it to understand how a format is assembled, fork it if you intend to diverge from the defaults, and file anything you find broken in the pandoc tracker rather than here. ## Dual licensed, GPLv2 or later and BSD 3-clause All of the templates in this repository are dual licensed, under both the GPL (v2 or higher, same as pandoc) and the BSD 3-clause license, and the README includes the BSD text in full. The dual licence is the practical point, because it removes the question that usually comes up with GPL-licensed material. A GPL v2 or later grant lets you use the templates under GPL terms, and the BSD 3-clause grant lets you use them under permissive terms. Choosing the permissive one is generally what a company wants when embedding a template into a proprietary pipeline, and the availability of that choice is the point of dual licensing. The BSD conditions themselves are the standard three. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. And neither the name of John MacFarlane nor the names of other contributors may be used to endorse or promote products derived from this software without specific prior written permission. The copyright line reads Copyright (c) 2014--2019, John MacFarlane, with All rights reserved. The name matches the author of pandoc itself, and the date range stops in 2019 even though the templates keep changing, which is normal for a project whose licence header is rarely rewritten. One thing to be aware of is that the repository listing records the licence as one GitHub cannot classify, while the README states the dual licence plainly and includes the BSD text. The README is the authoritative statement here, and the LICENSE file in the tree is the place to confirm it against the version you are using. ## What this repository is not It is worth being explicit about the boundaries, because the name invites a wrong assumption. It is not a collection of example documents or a gallery of what pandoc can produce. There are no sample .md files, no screenshots and no documentation of the template syntax here. The repository is the templates themselves and a licence. It is not a place to report a bug. The README is unambiguous that issues and pull requests should be made in pandoc's issue tracker, and that is the right place for anything about how a format renders, since that behaviour is pandoc's and not the template's. It is not a fork of pandoc itself, and it does not contain the converter. The templates are inert text files with placeholders that pandoc fills in. Using one requires pandoc. And it is not a place to track release notes. There are no GitHub releases here, and the README does not carry a changelog, because the release history that matters is pandoc's own. The primary language recorded for the repository is HTML, which is a small curiosity rather than a statement about the whole tree. Most of the files are HTML templates, and several of the largest are, so the classifier picks it, while the rest of the repository is LaTeX, XML, AsciiDoc, DocBook, Typst and a range of other markup formats. What the repository does offer is a complete, current picture of how pandoc renders each format, in one place, at a known version. For a documentation pipeline that needs to produce a dozen formats and keep them consistent, that inventory is the useful artefact. ## Conclusion pandoc-templates fits someone who needs to see how a specific pandoc output format is assembled, or who wants to start a custom template from the current default rather than from scratch. It is the wrong place to send a bug, since the README routes issues and pull requests to the pandoc tracker, and the wrong repository to depend on as a source of truth for changes, since edits land in pandoc first. Verify first which pandoc version you are targeting, because the templates are tied to releases, and read the fork advice in the README before you copy a template into your own project, because the upstream copy keeps changing with each release. ## FAQ ### What is the pandoc-templates repository? It contains the default templates for pandoc, one file per output format, covering HTML, LaTeX, EPUB, DocBook, JATS, reveal.js, Typst, Djot, ODT and many others. The templates are also split into reusable partials such as common.latex and fonts.latex. ### Where should I report a problem with a pandoc template? In the pandoc issue tracker, not here. The README says this repository is a subtree of pandoc that is updated on each new pandoc release, and that changes to templates are made first in pandoc, so issues and pull requests should be made there. ### Should I fork pandoc-templates if I want a custom template? The README recommends it. It says that if you use custom templates you should fork the repository so that you can integrate changes to the default templates in future pandoc releases, rather than copying a template into your project and letting it drift. ### What licence applies to the pandoc templates? All the templates are dual licensed under the GPL, version 2 or higher, the same licence as pandoc, and the BSD 3-clause license, whose text the README includes in full. The copyright line reads 2014--2019, John MacFarlane. ## Sources - [Issues](https://github.com/jgm/pandoc-templates/issues) - [jgm/pandoc-templates on GitHub](https://github.com/jgm/pandoc-templates) - [README](https://github.com/jgm/pandoc-templates/blob/master/README.md) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jgm-pandoc-templates