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 https://jez.io/talks/.

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:

• 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.

• 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.

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.

⚠️ 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.

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

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.

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

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.

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"