GitHub Pandoc HTML5 Template
GitHub Template v2.1 (2018/02/28) | pandoc v2.1.1
A pandoc html5 template mimicking GitHub's documents preview. Supports extended GitHub Flavored Markdown features through custom pp-macros that leverage Raw HTML and GitHub's CSS.
Table of Contents
This html5 pandoc template will format your documents using CSS based on GitHub's stylesheets. Beside covering the standard pandoc markdown elements, this template also supports some of GitHub's extra HTML styling:
- Inline highlighter via
- Keystrokes via
<kbd>tag (eg: Ctrl+Z)
- Task lists
- Alerts (aka Flash messages)
These elements can be integrated in pandoc source documents via our custom pp-macros for generating Raw HTML elements. For example, you can now use GFM Task Lists in your pandoc documents via the following pp-macros:
!TaskList( !Task[x][I'm a _checked_ task] !Task[ ][I'm an _unchecked_ task] )
… which will be preprocessed to Raw HTML:
<ul class="task-list"> <li class="task-list-item"> <input type="checkbox" disabled="" checked="" />I'm a <em>checked</em> task </li> <li class="task-list-item"> <input type="checkbox" disabled="" />I'm an <em>unchecked</em> task </li> </ul>
… and in the final document they will be rendered like on GitHub.
For a live preview, and the full list of template features, see:
In order to make the template available to pandoc system-wide, it should be copied to the
templates subfolder in pandoc's data dir — on Windows, that would be
%APPDATA%\pandoc\templates\; on *nix it would be
~/.pandoc/templates/. If you haven't installed any templates before, you'll have to create the
templates folder yourself.
On Windows, you can install/update the GitHub template via the batch script found in this folder:
Run it from the CMD or the File Explorer. The script will ask for confirmation before actually installing the template.
Once the GitHub template is installed to pandoc's templates folder, you'll be able to use it from anywhere via the
pandoc --template=GitHub.html5 FILENAME.md -o FILENAME.html
The GitHub template is a fully self-contained single-file template (no external stylesheets, all CSS is embedded in the template), therefore the output HTML file it produces can be distributed without need of any dependencies.
But if the document you are converting relies on external resources (images, additional CSS files, etc), and you want to produce a single-file HTML document, than you should use the
pandoc --template=GitHub.html5 --self-contained FILENAME.md -o FILENAME.html
--self-contained option will make pandoc use
data: URIs to incorporate into the final document the contents of linked scripts, stylesheets, images, and videos. The advantage of a self-contained document is that it can be moved around as a single-file without breaking it. The downside is document size and redundancy:
data: URIs resources are larger in size, and resources which appear more than once in the same document will be converted to a full
data: URI at each occurence — for large images occuring more than once, this could be an issue.
NOTE — the
--templateoption already implies
GitHub HTML5 Panodc Template is Copyright © Tristano Ajmone, 2017, released under The MIT License (MIT):
MIT License Copyright (c) Tristano Ajmone, 2017 (github.com/tajmone/pandoc-goodies) Copyright (c) Sindre Sorhus <firstname.lastname@example.org> (sindresorhus.com) Copyright (c) 2017 GitHub Inc. "GitHub Pandoc HTML5 Template" is Copyright (c) Tristano Ajmone, 2017, released under the MIT License (MIT); it contains readaptations of substantial portions of the following third party softwares: (1) "GitHub Markdown CSS", Copyright (c) Sindre Sorhus, MIT License (MIT). (2) "Primer CSS", Copyright (c) 2016 GitHub Inc., MIT License (MIT). Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
GitHub Markdown CSS
GitHub Markdown CSS is Copyright © Sindre Sorhus, released under The MIT License (MIT).
These template files are derivatives from GitHub Markdown CSS:
Primer CSS is Copyright © 2016 GitHub Inc., released under The MIT License (MIT).
These template files are derivatives from the Primer CSS project's modules:
src/_github-markdown.scss(borrows snippets from various Primer modules)
- v2.1 (2018-02-28)
$charset$template var to (optionally) override document enconding.
- v2.0 (2017-11-21) - Pandoc v2.x adaptation. - New system for building template from source files. - Stylesheet cleanup and improvements, now built from Sass SCSS source files.
- v1.1 (2017-04-10)
- Added new custom Alert class "
flash-plain" with greyish colors. (pp-macro:
- v1.0 (2017-04-09) - First release.