/ox-tufte

Emacs' Org-mode export backend for Tufte HTML

Primary LanguageEmacs Lisp

Ox-tufte

Introduction

This is an export backend for Org-mode that exports buffers to HTML that is compatible with Tufte CSS out of the box (meaning no CSS modifications needed).

It’s still a work-in-progress, but it works well right now.

Installation and Usage

You can install ox-tufte using MELPA:

(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)

(package-refresh-contents)
(package-install 'ox-tufte)

And then in your init.el:

(require 'ox-tufte)

For usage, when exporting simply select “Tufte HTML” instead of regular HTML export from the export menu (C-c C-e).

It’s important that you download tufte css and place it on your server (with the fonts) and then reference it from your org-mode document by adding a header such as:

#+HTML_HEAD: <link rel="stylesheet" href="/css/tufte.css" type="text/css" />

Features

ox-tufte supports most of the features from tufte-css, some in different ways than expected.

  • Footnotes become numbered Sidenotes from the tufte spec
  • Margin notes can be created by having a link to mn:<n> where the link text gets transformed to the margin note, for example:
This is some regular text [[mn:1][this will be a margin note]]
  • Anything in #+BEGIN_QUOTE blocks becomes an epigraph, where the #+NAME of the quote becomes a reference in the <footer> inside of the epigraph.
  • Verses (#+BEGIN_VERSE) are treated the same as quotes, however they preserve leading spaces in the text

Compatibility

Ox-tufte is compatible and tested with tufte-css v1.1, though it may work with later versions. Please open issues if you discover any incompatibility!

Customization

There is only a single customization right now, org-tufte-include-footnotes-at-bottom. Because footnotes are transformed to sidenotes they are currently hidden on very narrow screens (like phones), if you want to include footnodes also at the bottom of the page, this may be set to t.

TODOs

  • Add the ability to use the fullwidth class on figures
  • Support #+CAPTION better on images
  • Tufte image quilts?

References