blob: 26094d42e2b4e8ae51a1b93facb491dbc2d98244 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
#+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
|
