#+TITLE: Ox-tufte
#+AUTHOR: Lee Hinman
#+EMAIL: lee@writequit.org

* Introduction

This is an export backend for Org-mode that exports buffers to HTML that is
compatible with [[https://edwardtufte.github.io/tufte-css/][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 [[https://melpa.org][MELPA]]:

#+BEGIN_SRC emacs-lisp
(add-to-list 'package-archives
             '("melpa" . "http://melpa.org/packages/") t)

(package-refresh-contents)
(package-install 'ox-tufte)
#+END_SRC

And then in your ~init.el~:

#+BEGIN_SRC emacs-lisp
(require 'ox-tufte)
#+END_SRC

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 [[https://github.com/edwardtufte/tufte-css][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:

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

* 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:

#+BEGIN_SRC fundamental
This is some regular text [[mn:1][this will be a margin note]]
#+END_SRC

- 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 [[https://github.com/edwardtufte/tufte-css/releases][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
- https://edwardtufte.github.io/tufte-css/
- https://gitlab.com/snippets/22309