tufte-pandoc-jekyll¶ ↑

This is a Jekyll theme for using Tufte CSS alongside pandoc-sidenote. It's based off of

• Tufte CSS for the original CSS file

• Tufte Pandoc CSS uses Markdown in conjunction with Tufte CSS

You may ask, “What's the difference between this and tufte-jekyll?”

Using pandoc-sidenote, we don't have to use {% sidenote %}...{% sidenote %} and can instead just use [^1] like normal Pandoc markdown.

For a demo, see jez.io/talks/.

Features¶ ↑

This fork introduces some changes to the style sheets that are meant to provide support for using tufte-pandoc-jekyll alongside Pandoc-crossref and Reveal.js. Otherwise, this project attempts to match the style, features, and version numbering of tufte-pandoc-jekyll. In short what it does is to:

Figures, captions, and borders¶ ↑

• Provide basic support for pandoc-crossref subfigures.

• Correctly style <figcaption> even in margin figures, as generated by pandoc-crossref.

• Correctly style div > table > caption as generated by pandoc-crossref.

• Match table border color to main text color and collapse to avoid gaps and other rendering issues.

• Basic support for full-width iframes and for treating iframes as figures with captions, by using pandoc-crossref .subfigures syntax (results may be unexpected in some cases).

• Make <video> behave the same as <img>.

• Provide sensible formatting for collapsible <details> blocks.

Alignments and typography¶ ↑

• Fix the alignment of sidenotes generated by Citeproc citations inside Blockquotes.

• Fix the width of definition lists that are inside an ordered or unordered list.

• Style <h5>, <h6>, and <dt> to match <span class="newthought">; the rationale behind this is that a span provides no semantic structure to the document, whereas using headings follows the concept of run-in \paragraph and \subparagraph in LaTeX.

• Style Pandoc's .line-block (blocks where line breaks are preserved as-is, for example in poetry) to be consistent with the remainder of the text.

• Emphasized text belonging to a block that is in italics by default (epigraphs and level 2 and 3 headings) is made upright.

• Use the OpenType font-variant: all-small-caps for text using the default Pandoc span class {.smallcaps}.

• Use the OpenType font-variant: tabular-nums inside table cells.

• Flush table cell contents top even if the cell has a <p> in it, while preserving spaces between paragraphs.

• Pull the CSL styling already implemented in Tufte-Pandoc-CSS but not yet migrated to tufte-pandoc-jekyll.

Reveal.js and bonus features¶ ↑

The following tweaks allow you to use the same Markdown file as a base for a regular web page and for a Reveal.js slideshow. These features are not enabled by default. To enable then, check out assets/css/main.scss from the theme files and uncomment the @import "revealjs-support" ; line.

• Provide basic support for Reveal.js columns (only two equal or unequal columns work well for now; for further details, see the Pandoc docs).

• Correct the width of speaker notes and incremental blocks used by Reveal.js to match that of regular paragraph text.

• Provide a dark color scheme based on a softened inversion of the main colors as well as the solarized dark scheme for code.

• A blank _local.scss file for any customization you might want to make.

:warning: The Reveal.js support does not affect slide output in any way and you should not point your slide presentation to the styles in the tufte-pandoc-jekyll theme. These features are meant to normalize the appearance of the text version of your page when it contains markup that will also be used for slide output.

Installation¶ ↑

There are two external dependencies in order to use this theme. You can install them through your package manager (like apt-get or brew):

# EXAMPLE: This is for macOS. Change if you're on Linux.
# Note: you must have pandoc version 2.0 or greater
brew install pandoc
brew install jez/formulae/pandoc-sidenote

Next, add this line to your Jekyll site's Gemfile:

gem "tufte-pandoc-jekyll"

And add these lines to your Jekyll site's _config.yml:

theme: tufte-pandoc-jekyll

gems:
  - jekyll-pandoc

And then execute:

$ bundle

Or install it yourself as:

$ gem install tufte-pandoc-jekyll

Usage¶ ↑

Note: while tufte-pandoc-css optionally includes the Solarized Light/Dark colorscheme, it's enabled by default here, with no easy way to opt-out. This is probably fine for you, but if it's not, feel free to make a PR that allows opting out.

Variables¶ ↑

The following variables are used by this theme.

• site.title

• site.author

• Note that this theme currently only supports one author.

• site.baseurl

• Make sure you don't have a trailing slash here

• site.header_includes

• page.header_includes

• You can use these to include raw HTML in the <head>

• site.include_after

• page.include_after

• You can use these to include raw HTML in the <body> before the content

• site.include_before

• page.include_before

• You can use these to include raw HTML in the <body> after the content

• page.layout

• Pick one of index, page, or post

• index won't have a “Return home” link at the bottom of the page

• page.title

• page.subtitle

• page.date

• page.keywords

• page.math

• If true, we'll include KaTeX for displaying math formulas

_config.yml¶ ↑

You'll need to update your _config.yml to compile the site using Pandoc. Make sure you've followed the installation instructions.

gems:
  - jekyll-pandoc

markdown: Pandoc
pandoc:
  extensions:
    - section-divs
    - from: 'markdown+tex_math_single_backslash'
    - filter: 'pandoc-sidenote'

Optional: remove section-divs if you want to insert <section> tags manually.

Developing¶ ↑

To make a release:

vim tufte-pandoc-jekyll.gemspec
git commit tufte-pandoc-jekyll.gemspec -m 'Bump version'
git tag "$version"
git push --tags origin master
gem build tufte-pandoc-jekyll.gemspec
gem push "tufte-pandoc-jekyll-$version.gem"

License¶ ↑