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 aspan
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
, orpost
-
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"