This project provides CSS files and a template for using Pandoc⊕Pandoc is a “universal document converter.” It is particularly good at generating HTML and \LaTeX from Markdown.

to generate standalone HTML files. It supports most features Pandoc Markdown has to offer, and some extras. The default look can be tweaked via CSS variables, and it does not need JavaScript, even for side notes.

Features

A short list of headline features:

• Code blocks, including:
  • Syntax themes
  • Line numbers and line highlights
  • Extra wide and full-width options
  • Captions
• Images and tables, including:
  • Extra wide and full-width options
  • Captions
• Side notes and margin notes
• Floating table of contents
• \LaTeX math, rendered via \KaTeX in the browser
• Dark mode, based on the user’s default color scheme preference

For the complete feature set, see the documentation. You might also want to view the “kitchen sink” page that is useful when developing, or the source code:

→ Documentation
→ Kitchen Sink
→ Source on GitHub

The theme is fully responsive, including phones, tablets, laptops, and wide desktop screens. Side notes and the table of contents display inline on small screen sizes, and in the margins on wide enough screens. Extra wide images, tables, and code blocks shrink when space isn’t available. CSS @media print styles declare first-class print styles.

The source code is extremely tweakable.⊕When changing things like the font family or font size, the thing that matters is to pay special attention to alignment. Different fonts have different x-heights and widths. Most layouting can be agnostic of these things, but there are explicit variables for places where it matters.

A small set of CSS variables control a large number of font and color settings: you don’t have to hunt down all the places that need to be changed to tweak the design. As a proof of concept, see this page, which tweaks the default theme slightly. These same CSS variables power the light- and dark-mode versions of the theme. Of course, the code is open source and you’re welcome to copy the theme files and completely overhaul them if desired.

And finally, there’s basically only HTML and CSS. The theme doesn’t use custom fonts by default, and only uses JavaScript for two things:

• Rendering math (via \KaTeX), only if used.
• Slightly tweaking the appearance of checklist items. (Pandoc emits them as disabled, but they look better when enabled in my opinion.) This is entirely presentational.

Placement of side notes, the table of contents, and code block line highlights are all controlled with CSS. See the credits below for more background on the techniques used.

Usage

This project merely provides a CSS files and a standalone HTML template to give to Pandoc. The imporant files that you might want to copy out to start your own project:

• public/css/theme.css, the core CSS implementing theme
• template.html5, the Pandoc template that renders Markdown to HTML
• Makefile, showcasing the Pandoc flags required to get things to build
• src/index.md, the source code for this page

To see things in action, try rebuilding this site locally. First, you’ll need a few command line programs:

• Pandoc
• pandoc-sidenote
• realpath from GNU coreutils
• (optional) watchman, for rebuilding when files change

Follow the installation instructions for your platform. If you’re using macOS, installation is as easy as:

brew install pandoc coreutils
brew tap jez/formulae
brew install pandoc-sidenote

Then you can clone this project and run make watch:

git clone https://github.com/jez/pandoc-markdown-css-theme
cd pandoc-markdown-css-theme

# Test everything by forcing a clean build
# (the generated comes with the clone)
make clean
make

# If you installed watchman
make watch

Running make will build everything in the site.

Running make watch will start a webserver at http://127.0.0.1:8000/, open that URL in a web browser, and watch files for changes in the background.

Usage with Jekyll

While the core theme is just a handful of static files that can be copied into any project, using this theme with Jekyll is as easy as installing a theme:

→ Pandoc Markdown Jekyll Theme

Check the project above for installation and usage instructions with Jekyll.

Credits

First, thanks to Pandoc, by John MacFarlane, for being an all-around awesome tool, especially for Markdown.

The core technique for laying out side notes⊕Gwern has a great survey post that discusses Sidenotes In Web Design, covering the techniques in Tufte CSS as well as the limitations, and many alternatives.

I learned from Tufte CSS, by Dave Liepmann. The technique is described in detail here. Tufte CSS suggests writing the HTML for sidenotes by hand, but I wanted to use Markdown. I wrote pandoc-sidenote, a Pandoc filter that traverses Pandoc’s internal AST and converts footnote nodes into the HTML side note markup for Tufte CSS-style side notes.

While the idea for side notes comes entirely from Tufte CSS, the implementation at this point is almost completely different. Tufte CSS uses relative widths everywhere, but I wanted a body with a constant width at all but the smallest screen sizes. Tufte CSS renders the main body off center. Rendering centered when possible and off center when not adds complexity in the implementation.

The inspiration for code block line highlights comes from a change I contributed to pandoc-emphasize-code, by Oskar Wickström (another Pandoc filter). I decided against using it for this project because it forces a choice of either line highlights or syntax highlighting per code block (unless you tack on a JavaScript-based syntax highlighter, like Highlight.js). I thought of a clever technique using CSS clases to avoid this.

Considerable design inspiration comes from Dropbox Paper, a gorgeous and powerful tool. (In fact, the theme is customizable enough to recreate the look of Paper. This is provided for educational purposes only, under Fair Use.)

See also

If you’d like to use Tufte CSS with Pandoc in your own project, feel free to use my Tufte Pandoc CSS project.

If you’d like to use this theme in a Jekyll project, I have already packaged these files as a Jekyll theme: pandoc-markdown-jekyll-theme.

↑ Back to the top