jez/tufte-pandoc-css

Starter files for using Pandoc Markdown with Tufte CSS

Tufte Pandoc CSS

Starter files for using Pandoc Markdown with Tufte CSS

This project aims to provide a standard set of project starter files for working with Pandoc and Tufte CSS. It features:

• extra CSS styles for things like tables and syntax highlighted code
• tweaks to the CSS to get HTML produced by Pandoc to play nicely with Tufte CSS
• an optional Solarized light color scheme for code blocks
• a modular separation of these components--you can select which you want
• an HTML5 template file that sets up the document the way Tufte CSS expects
• support for lots of Pandoc markdown features, including
  • footnotes as side notes
  • footnotes as margin notes
  • metadata like title, subtitle, date, and author
  • LaTeX using MathJax or KaTeX

Apart from projects like Tufte CSS & Pandoc, the main project that enables this project is pandoc-sidenote, a project which converts Pandoc Markdown-style footnotes ([^1]) into side notes.

Looking to use this with Jekyll?

You might be interested in Tufte Pandoc Jekyll, which wraps the files distributed here into a Jekyll gem-based theme.

Looking for the same features, but a different look?

You might be interested in Pandoc Markdown CSS Theme, a theme with much of the same features as this theme, but with a more easily customizable look.

Table of Contents

• Background
• Installation
• Usage
• License

Background

If you haven't already, I encourage you to explore the projects that have been built on top of here:

• Pandoc - a universal document converter
• Tufte CSS - style your webpage like Edward Tufte's handouts
• pandoc-sidenote - convert Pandoc Markdown-style footnotes into sidenotes

Installation

Dependencies

This project is always tested relative to:

• the most recent master commit of tufte-css.
• the latest release version of pandoc

In particular, you'll need at least Pandoc version 2.0.

This project is meant to be a set of starter files for your next project. What that ultimately means is that you should use these files however your heart sees fit. In practice, here are some tips for some things you may want to do to get set up.

First, install pandoc-sidenote to your PATH.

• This lets pandoc compile footnotes into sidenotes.
• Instructions are on the pandoc-sidenote homepage.

Second, download tufte.css and the et-book/ font folder.

• Head over to tufte-css to download these.
• You should be able to work with any version of Tufte CSS, assuming things haven't changed too much.
• If things don't seem to be working, try using the version stashed in the tufte-css/ folder in this repo (it's a submodule).

Third, there are a number of static files you can download and place where you see fit:

• tufte.html5
  • This is an HTML5 compatible template for use with Pandoc's --template flag.
  • It sets up the document structure in a way Tufte CSS expects.
• pandoc.css
  • This CSS file has styles for things like sections, author & date information, highlighted code blocks, and tables.
• pandoc-solarized.css (optional)
  • This sets up highlighted code blocks to use the Solarized Light color theme
• tufte-extra.css (optional)
  • This makes some "personal preference" tweaks to Tufte CSS. It is NOT required.

Finally, you'll want the Makefile.

• The Makefile usage is explained below.

Usage

The best way to learn to use this project is to read the documentation--both online and in the source code. You'll probably want to look through things in this order

1. The re-implementation of the Tufte CSS homepage in Pandoc Markdown

• Remember to read the source!

1. The Tufte Pandoc CSS homepage, which documents the additional features specific to this project.

• Remember to read the source!

1. The included [Makefile], which compiles *.md files into *.html files using pandoc with the correct options.
2. The Pandoc homepage. Not everything you see here will work with this project, but if you think something should work that doesn't, open an issue.
   • You'll probably want to just skim this... it's lengthy!

Once you have an understanding of what Markdown features are available, you can use the Makefile to compile your Markdown files.

For example, this is how we build the homepage for this site:

make docs/index.md

and here's how we build all the site files:

make docs
make

Assuming you've laid out your directory identically to this repo, you can pass the name of any *.md file to convert it into an appropriately named *.html file.

make my-pandoc-markdown-file.md

License

tufte-pandoc-css's Issues

Clarification about code block wrap width

The first code block is wrapped properly while the second is not. Is this a design choice? If so, would you mind explaining the rationale behind it?

On a different note, many thanks for your work especially on pandoc-sidenotes. It is a supremely useful library and has saved me many hours of experimentation.

No css for bibliography?

I was compiling HTML from markdown using pandoc with the --citeproc option, and I noticed that the bibliography looked bad (basically because there's no hanging indent).

Here is an example with tufte-pandoc-css

Compare to the following (with the default css), it's clear that the lack of hanging indent makes it pretty unreadable.

This seems to be caused by the fact that no classes such as div.csl-entry are defined in tufte-css, or in the additional css files in this repo.
I hacked together a quick fix by copying things from the default css. This is what I added:

div.csl-bib-body {
  /* font-size: 1.4rem; */
  /* line-height: 2rem; */
  width: 55%;
}
div.csl-entry {
  clear: both;
  margin-top: .25em;
}
.hanging div.csl-entry {
  margin-left:2em;
  text-indent:-2em;
}
div.csl-left-margin {
  min-width:2em;
  float:left;
}
div.csl-right-inline {
  margin-left:2em;
  padding-left:1em;
}
div.csl-indent {
  margin-left: 2em;
}
div.hanging-indent{
  margin-left: 1.5em;
  text-indent: -1.5em;
}

@media (max-width: 760px) {
  div.csl-bib-body {
    width: 100%;
  }
}

to get the following

This is better. But, a more comprehensive fix would be needed to make this work with arbitrary CSLs, I think (I'm just using the default Chicago author-year CSL, ones that make numbered references (e.g. Springer, or IEEE) would need additional attention.) Am I missing something, and is this fix not needed? Is fixing this something within the scope of this project?

(Also, This repo is great. Thanks for putting it up!)

Code blocks overlap with headings

Code blocks overlap with headings above them.

Expected:

Actual:

The problematic code is found in line 55 of pandoc.css

This issue can be resolved by changing:

margin: -0.7rem -1.4rem;

to:

margin-left: -0.7rem;

---

I would typically just open a PR for this, but I am not sure about which tufte-css repo to sumbit changes to.

Some other repos affected (afaik):

• markdown2tufte

Thanks for this great project, btw.