From LaTeX to Hugo

Every feature of tufte-handout and tufte-book, in Markdown

This page maps every feature of the tufte-handout and tufte-book LaTeX classes to the Markdown, shortcode or setting that does the same with this theme, and then shows each shortcode at work. The two ports of the Tufte-LaTeX samples, the handout and the book, show them in context.

The table is in “The cheat sheet”, and the live examples start with “Notes”.

The cheat sheet

The status column says how complete the counterpart is: must and should features are implemented, could features are extras, and wont rows explain why a LaTeX feature has no web counterpart. Option names such as tufte.justified are keys of [params.tufte] in the site configuration, or of the tufte: map in a page’s front matter. Rows 107–117 are the theorem environments of the amsthm package, which the classes do not define but mathematical texts load with them.

Placement rule. Inline shortcodes (sidenote, marginnote, footnote, cite, xref, eqref, label, index, footnotemark, newthought, sans, allcaps, smallcaps, sc, textls, nohyphens, paragraph, bibentry, nocite, and marginfigure with inline="true") are written inside a paragraph. Block shortcodes (figure, fig, table, marginblock, equation, footnotetext, bibliography, printindex…) stand alone, with blank lines around them.
#tufte-latextufte.hugoStatusNotes
1\documentclass{tufte-handout}any page outside a bookmustbody class tufte-handout
2\documentclass{tufte-book}a section whose _index.md (or content/_index.md, for a whole-site book) sets book: truemustits pages are the chapters; see Books
3class options (justified, sfsidenotes, nols, marginals…)[params.tufte] in the site config; tufte: in front mattermustresolved key by key: page → part → book → site → style preset
4“looks like tufte-handout”tufte.style = "latex"shouldpreset: LaTeX title block, hyphenation, indented paragraphs, old-style figures, plainnat, running heads
5\sidenote{}, \footnote{}{{< sidenote >}}…{{< /sidenote >}}, Markdown [^1]musttufte-latex’s \footnote is a sidenote; footnote ids are deterministic
5aa classic footnote (\footnote of the article class){{< footnote >}}…{{< /footnote >}}, Markdown [^fn-x] (any [^x] with footnotes = "endnotes")mustlisted below the text, numbered apart from the sidenotes; see Footnotes and sidenotes
6\sidenote[num][offset]{}{{< sidenote number="*" offset="-2bl" >}}…{{< /sidenote >}}musta custom number does not step the counter
7\marginnote[offset]{}, \marginpar{}{{< marginnote offset="1bl" >}}…{{< /marginnote >}}must
8multiple marks (\multfootsep)automaticcouldadjacent marks (sidenotes and real footnotes) are separated by a comma
9\footnotemark + \footnotetext[offset]{}{{< footnotemark "row3" >}} + standalone {{< footnotetext name="row3" offset="-7bl" >}}…{{< /footnotetext >}}shouldno other numbered note between mark and text
10\label on a sidenote (“see note 7”){{< sidenote label="sn:x" >}}…{{< /sidenote >}}should{{< xref "sn:x" >}} prints its number
11block content in the margin{{< marginblock >}}…{{< /marginblock >}}shouldparagraphs, lists, tables; toggled on mobile
12\cite[offset]{a,b}{{< cite "a,b" >}}, {{< cite "a" "b" >}}, {{< cite keys="a,b" offset="-1bl" >}}mustthe full reference as a numbered sidenote
13\cite inside \sidenote, \marginnote, \captiona nested {{< cite >}}, or cite="a,b" on the note or figureshouldthe reference is appended under the note
14natbib \citet, \citep, \citeauthor, \citeyear (+ page){{< cite keys="a" mode="text" page="42" >}}; modes text, paren, author, yearcouldinline text, no sidenote
15\bibentry{key}{{< bibentry "key" >}}mustthe formatted entry, inline
16\bibliography{f} + \bibliographystyleautomatic at the end of a handout; {{< bibliography >}} anywhere (standalone)musttufte.bibliography.style = "tufte" (citation order) or "plainnat" (sorted; with nobib the [n] follow the sorted list)
17\nobibliographytufte: {bibliography: {list: false}}must
18\nocite{a}, \nocite{*}{{< nocite "a,b" >}}, {{< nocite "*" >}}, front matter nocite: [a]should
19class option nobibtufte.bibliography.margin = falseshoulda citation becomes [n], linked to the list (numbered in the order of bibliography.style)
20.bib databasedata/bibliography.yaml (native), data/bibliography.json (CSL-JSON), front matter bibliography: refs.json or references:mustsee Bibliography
21.bib read directlybibliography: refs.bib (page resource or asset)coulda simple BibTeX reader; pandoc → CSL-JSON is more robust
22\doi{}, \url{} in entriesfields doi, urlmustrendered as links
23figure + \caption + \label{{< figure src="…" caption="…" label="fig:x" >}}; ![alt](src "caption") + {#fig:x}; {{< fig src="…" label="fig:x" >}}caption{{< /fig >}}must“Figure N:” starts the margin caption
24\caption[short]{}short="…"shouldused in the list of figures
25\caption[][offset]{}offset="1bl"should
26\setfloatalignment{b}, [b]captionpos="bottom"shouldcaption aligned with the bottom of the float
27figure*{{< fullwidthfigure >}}, type="fullwidth", {.fullwidth}mustthe caption floats in the margin column
28marginfigure[offset]{{< marginfigure offset="…" label="…" >}}, {{< fig type="margin" >}}must
29figure without captionany figure without captionmustunnumbered
30table + \caption{{< table caption="…" label="tab:x" >}} + a Markdown table; a Markdown table + {#tab:x caption="…"}mustits own counter
31table*{{< fullwidthtable >}}, {{< table type="fullwidth" >}}should
32margintable[offset]{{< margintable caption="…" offset="…" >}}…{{< /margintable >}}should
33booktabsMarkdown tablesshouldrules come from the CSS; \cmidrule and \multicolumn are wont (no Markdown syntax)
34algorithm / listing floats{{< listing caption="…" label="lst:x" style="ruled" >}} + a fenced code blockcouldstyles plain, ruled, boxed
35subfigures, \fbox image grids{{< subfigures cols=2 type="fullwidth" caption="…" >}} with images on consecutive linescouldlinked images (thumbnails) keep their link and subcaption
36\ref{{< xref "fig:x" >}}mustforward references work
37Figure~\ref{fig:x}{{< xref "fig:x" "full" >}}mustwith a non-breaking space
38\nameref{{< xref "sec:x" "name" >}}must
39\pageref{{< xref "err:x" "page" >}}shouldthe enclosing section title; in a book, the chapter title for a target in another chapter
40\eqref{{< eqref "eq:x" >}}should“(3)”
41\label anywhere{{< label "err:x" >}}should
42\listoffigures, \listoftables{{< listoffigures >}}, {{< listoftables >}}, {{< listoflistings >}} (standalone)shouldthe whole book inside a book, else the page
43numbered equations + \label$$ … \label{eq:x} $$, {{< equation label="eq:x" >}}…{{< /equation >}}should
44\chapter{}, \chapter[short]{}a page of the book: title, linkTitlemust
45\chapter*{}unnumbered: trueshould
46\part{}a sub-section (_index.md) inside the bookshouldroman numerals
47\frontmatter, \mainmatter, \backmattermatter: front, main, backshouldonly main matter is numbered
48\appendixmatter: appendixshouldlettered A, B, …
49\tableofcontents (book)automatic on the book’s landing page; {{< tableofcontents >}}mustitalic, no leaders
50\tableofcontents (handout)front matter toc: true; {{< tableofcontents >}}must
51\maketitle (full title page)the book’s landing pagemusttufte.book.titlepage
52\maketitle (handout title block)tufte.titleBlock = "latex"shoulditalic author and date lines
53\title[plain], \author[plain], \publishertitle, linkTitle, author, publisher, publisherPlainshould
54\date{}, \date{text}showDate: false, dateText: "Spring 2026"shoulddate stays the sort key
55\thanksthanks: "…", author: [{name: …, thanks: …}]shoulda sidenote in the title
56abstract environmentfront matter abstract:, {{< abstract >}}…{{< /abstract >}}should
57\openepigraph, epigraph pagesbook root epigraphs:; {{< epigraph style="open" >}}should
58epigraph (tufte-css){{< epigraph >}}must
59copyright pagebook root copyrightPage:shouldMarkdown string or {year, holder, publisher, url, license, printing}
60dedicationbook root dedication:should
61frontispiecebook root frontispiece: {src, alt, caption}couldan unnumbered figure, caption in the margin, before the title page
62\blankpage, \cleardoublepage, \clearpage{{< clearpage >}}; halftitle: truecouldprint only
63running heads (fancyhdr)tufte.print.runningHeads = truecouldprint only, Chromium ≥ 131
64the book printed as one PDFbook root outputs: [html, rss, print] → …/print.htmlshouldsee Printing
65\index{…} with !, @, |see{}, |seealso{}, |(, |){{< index "classes!a4paper" >}}, same syntaxshould
66\printindex{{< printindex >}} (standalone)shouldthree columns
67the index as a site taxonomy—wont/index/ clashes with Hugo’s index files; use the shortcode
68counters continuous across a booktufte.book.continuous = true (default)should
69\section, \subsection (italic, unnumbered)##, ###mustin \Large and \large (1.68rem, 1.54rem) with style = "latex" or titleBlock = "latex", below the title; tufte.css’s sizes otherwise
70\paragraph{} (run-in)#### Title, or {{< paragraph >}}Title{{< /paragraph >}}should
71no \subsubsectiona warning on #####/######; tufte.headings.strict = true makes it an errorshouldBringhurst §4.2.2
72secnumdepthtufte.headings.number = 0, 1 or 2; {.unnumbered}could
73\section[short]{} in the TOC—wontHugo builds its TOC from the headings themselves
74\newthought{}{{< newthought >}}…{{< /newthought >}}must
75\tuftebreak, \tufteskip{{< tuftebreak >}}could
76\allcaps{}{{< allcaps >}}…{{< /allcaps >}}, {{< allcaps "nasa" />}}must
77\smallcaps{}{{< smallcaps >}}…{{< /smallcaps >}}must
78\textsc{}{{< sc >}}…{{< /sc >}}should
79\textls[n]{}{{< textls "100" >}}…{{< /textls >}}couldthousandths of an em, or a CSS length
80ls, nolstufte.letterspacingshould
81\textsf, \sffamily{{< sans >}}…{{< /sans >}}must
82justified, ragged right, hyphenationtufte.justified, tufte.hyphenate, {.justify}, {.raggedleft}must
83sidenote=, marginnote=, caption=, citation=, marginals=tufte.marginals, tufte.sidenote.align, …should
84\setsidenotefont and friendstufte.sidenote.font = "italic sans"shouldwords: italic upright sans serif mono small smaller normal #hex
85sfsidenotestufte.sfsidenotes = truemust
86book \parindent paragraphstufte.indent = trueshould
87old-style figures (mathpazo osf)tufte.numerals = "oldstyle"could
88fonts, nofontsparams.etBookmust
89fullwidth environment{{< fullwidth >}}…{{< /fullwidth >}}must
90quote, quotationMarkdown >; {{< blockquote >}}must
91verse{{< verse >}}…{{< /verse >}}should
92description listsMarkdown definition listsshould
93mathKaTeX: $…$, $$…$$, \(…\), \[…\]mustsee Math
94\nohyphens{}, \nohyphenation{{< nohyphens >}}…{{< /nohyphens >}}, {.nohyphens}could
95\FloatBarrier{{< clearmargin >}}couldclear: right
96debug optiontufte.debug = truecouldoutlines and extra warnings
97letter, a4paper, b5papertufte.print.paper = "letter", "a4", "b5"mustgeometry from tufte-common.def
98symmetric, \forcerectofloat, \forceversofloat—wonta screen has no spreads, and a float cannot change side per printed page
99twoside, oneside—wontfolded into running heads: a book alternates (book title on left pages, chapter title on right pages); a handout prints its title and the page number at the top right of every page but the first
100bidithe language’s direction (<html dir>)could
101hyper, colorlinks, PDF metadata—wontlinks are native; colours via customCSS; metadata is in <head>
102tufte-*-local.tex hooksparams.customCSS, the *_custom.html partialsmustbody classes tufte-book/tufte-handout allow scoping
103\hangp, \hangleft, \hangstar—wontsample-book macros, not class features; CSS hanging-punctuation (Safari only) is used
104setspace doublespace—wontloaded by tufte-common.def, but it is a general line-spacing package, not a class feature: set the leading with CSS (line-height) through customCSS
105doc macros (\doccmd…), text shortcuts (\TL, \monthyear)inline code, your own shortcodeswontnot class features
106TeX machinery (\morefloats, engine detection, \TufteRecalculate, other paper options)—wontno meaning in HTML
107amsthm \newtheorem{k}{Word}{{< theorem >}}…{{< /theorem >}}, lemma, proposition, corollary, definition, example, remark; any kind with {{< thm "k" >}}…{{< /thm >}}; tufte.theorems.kinds.k.nameshouldthe amsthm package, not a class feature; see Theorems and proofs
108amsthm \newtheorem*{k}{Word}tufte.theorems.kinds.k.numbered = false; numbered=false on one theoremshould
109amsthm \newtheorem{k}[c]{Word} (shared counter)tufte.theorems.kinds.k.counter = "c"shouldevery kind shares theorem by default (tufte.theorems.shared), as in amsart.template
110amsthm \newtheorem{k}{Word}[section], \numberwithintufte.theorems.kinds.c.within, tufte.theorems.within: "section", "chapter", "none", "auto"shouldauto: per chapter in a book with numbered chapters or book.continuous = false (without numberChapters every chapter restarts at 1, no prefix), else through the page or the book
111amsthm \theoremstyle{plain|definition|remark}tufte.theorems.kinds.k.style; style= on one theoremshould
112\begin{theorem}[note] + \label{{< theorem "note" "thm:x" >}}…{{< /theorem >}}, {{< lemma note="…" label="lem:x" >}}shouldthe note in parentheses after the number; a {{< label "thm:x" >}} in the body refers to the theorem too
113amsthm proof, \begin{proof}[Head]{{< proof >}}…{{< /proof >}}, {{< proof "Head" >}}, {{< proof of="thm:x" >}}should“Proof of Theorem 2.1.”
114\qedhere, \qedsymbol{{< qedhere >}}, \qedhere in display math; tufte.theorems.qed, qed=shouldblacksquare ■ (css), openbox □ (latex), none or any text
115\ref, cleveref \cref, \nameref to a theorem{{< xref "thm:x" >}}, {{< xref "thm:x" "full" >}}, {{< xref "thm:x" "name" >}}should“2.1”, “Theorem 2.1”, the note
116thmtools \listoftheorems{{< listoftheorems >}} (standalone)shouldkinds="theorem,lemma", heading=""
117\swapnumbers, \newtheoremstyle, thmtools restatable—wontheads come in two looks (tufte.theorems.look: tufte, amsthm); restyle one kind with thm-kind-k in customCSS
118\usepackage{euler}, eulervm[params.math] font = "euler"; front matter mathFont: eulercouldMathML set in the bundled Euler Math font; text and \text{…} stay in ET Book
119\usepackage{libertinus}, libertinus-otf[params] font = "libertinus" and [params.math] font = "libertinus"; front matter font, mathFontcouldLibertinus Serif, Sans and Mono for the text, Libertinus Math (MathML) for the formulas
120Beamer slides of a handoutoutputs: ["html", "slides"]: slides.html, a reveal.js deckcoulda slide at each ## and ---; {{< notes >}} for speaker notes
121\usepackage{sourceserifpro}, sourcesanspro, sourcecodepro[params] font = "source"; front matter fontcouldSource Serif 4 for the text, Source Sans 3 for the sans-serif; Source Code Pro is the code font of every page but Libertinus’s

Notes

A sidenote can carry a label, like LaTeX’s \label inside \sidenote.This is the labelled sidenote. Its number is printed wherever it is referenced. A note may contain other inline shortcodes: a reference to Figure 2, or Small Caps. The text can then refer to Note 1, or simply to note 1. A margin note can be moved down by two baselinesThis margin note was written with offset="2bl". or up with a negative offset, and a Markdown footnote becomes a sidenote.Written as [^fn], like \footnote in LaTeX.

tufte-latex has no classic footnotes: its \footnote is a sidenote. When a note belongs below the text, as in a standard LaTeX article, the footnote shortcodea and Markdown footnotes whose label starts with fn-b give one, next to the sidenotes.

A margin block holds block content:

  • a list,
  • a second paragraph,
  • or a small table.

It is LaTeX’s \marginpar with a minipage inside.

The margin block next to this paragraph is a marginblock shortcode. Like every float, it is anchored where it is written, so it is placed between paragraphs.

A table can carry note marks whose text is set apart, as with \footnotemark and \footnotetext:

Table 1: A table with a note mark.
PaperText widthMargin
letter26 pc12 pc
a4107 mm49.4 mm

The width of the main text block, from tufte-common.def.

Citations

A citation is a numbered sidenote with the full reference,Edward R. Tufte. The Visual Display of Quantitative Information. Graphics Press, Cheshire, Connecticut, 2001. ISBN 0-9613921-4-2 several keys can be cited at once,Edward R. Tufte. Envisioning Information. Graphics Press, Cheshire, Connecticut, 1990. ISBN 0-9613921-1-8; and Edward R. Tufte. Visual Explanations. Graphics Press, Cheshire, Connecticut, 1997. ISBN 0-9613921-2-6 and the note can be moved like any other.Edward R. Tufte. Beautiful Evidence. Graphics Press, LLC, first edition, May 2006. ISBN 0-9613921-7-7; and Robert Bringhurst. The Elements of Typography. Hartley & Marks, 3.1 edition, 2005. ISBN 0-88179-205-5 In the natbib style, Tufte (1990) prints the author and year in the text, and (Tufte 2001, p. 92) puts them in parentheses. The full entry can also be written inline: Robert Bringhurst. The Elements of Typography. Hartley & Marks, 3.1 edition, 2005. ISBN 0-88179-205-5. The book by Mittelbach and Goossens is in the bibliography below without being cited, thanks to nocite.

Floats

A helixFigure 1: A margin figure whose caption cites a book: the helix x=cos⁡(2πz)x = \cos(2\pi z), y=sin⁡(2πz)y = \sin(2\pi z).Edward R. Tufte. Visual Explanations. Graphics Press, Cheshire, Connecticut, 1997. ISBN 0-9613921-2-6

Figures and tables are numbered automatically as soon as the page has a labelled float or equation, or any cross-reference (xref or eqref, to anything, a section included); tufte.floats.number = false turns this off. The margin figure here is Figure 1; its caption contains a nested citation.

Figure 2: Hilbert curves of degrees 1 to 5, a main-column figure.Hilbert curves

A plain Markdown image becomes a numbered figure when it has a title and an id:

The graph of y = sin x
Figure 3: A Markdown image with {#fig:demo-sine .fullwidth} on the next line.

That was Figure 3.

Table 2: A margin table.

nn²
11
24
39

Table 2 sits in the margin. The next one spans the whole page, like table*:

PaperPage sizeMargins (top right bottom left)Text columnMargin column
letter8.5 × 11 in1in 0.86in 1.48in 1in65%30%
a4210 × 297 mm27.4mm 20.6mm 28.2mm 24.8mm65%30%
b5176 × 250 mm28.7mm 14.69mm 34.1mm 14.66mm70%25%
Table 3: A full-width table: the paper geometry of the print stylesheet.
Listing 1: A listing float with the ruled style.
func main() {
	fmt.Println("Hello, Tufte")
}
Figure 4: Two title pages side by side, as a grid of sub-figures.
Title page of Envisioning InformationTitle page of Beautiful Evidence

With type="margin" the grid is a margin figure, its caption below it:

Title page of Envisioning Information(a) Envisioning InformationTitle page of Beautiful Evidence(b) Beautiful Evidence

Figure 5: The same title pages as a grid in the margin.

The lists of figures and tables of this page:

List of Figures

  1. 1 A helix
  2. 2 Hilbert curves
  3. 3 A Markdown image with {#fig:demo-sine .fullwidth} on the next line.
  4. 4 Two title pages side by side, as a grid of sub-figures.
  5. 5 The same title pages as a grid in the margin.

List of Tables

  1. 1 A table with a note mark.
  2. 2 A margin table.
  3. 3 A full-width table: the paper geometry of the print stylesheet.

List of Listings

  1. 1 A listing float with the ruled style.

Cross-references

A reference prints a number (2), a number with its name (Figure 2), the caption or the title (“Notes”), or the place where the target is (Cross-references). Forward references work: equation (1) is defined in the next section. An arbitrary point of the text gets a label with the label shortcode, like here.

Equations

A display equation with \label is numbered:

∫−∞∞e−x2 dx=π \int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi} (1)

So is one written with the equation shortcode:

eiπ+1=0e^{i\pi} + 1 = 0(2)

Equations (1) and (2) share one counter.

Theorems

The theorem environments of amsthm are block shortcodes, written {{< theorem "Euler" "thm:demo-euler" >}} (the note, then the label) and {{< proof >}}:

Theorem 1 (Euler). For every real xx, eix=cos⁡x+isin⁡xe^{ix} = \cos x + i \sin x.

Proof. Split the power series of eixe^{ix} into its even and odd terms:

eix=∑n≥0(ix)nn!=∑k≥0(−1)kx2k(2k)!+i∑k≥0(−1)kx2k+1(2k+1)!. e^{ix} = \sum_{n \ge 0} \frac{(ix)^n}{n!} = \sum_{k \ge 0} \frac{(-1)^k x^{2k}}{(2k)!} + i \sum_{k \ge 0} \frac{(-1)^k x^{2k+1}}{(2k+1)!}. ■

At x=πx = \pi, Theorem 1 gives (2). The \qedhere in the display puts the end-of-proof symbol at its right end. Theorems and Proofs shows the other kinds, shared counters, numbering within sections and the list of theorems.

Typography

Letterspacing is applied to all capitals, to Small Capitals, to Mixed Small Caps and, on request, to any text. A word can be protected from hyphenation: incomprehensibilities. The one-line form nasa works too.

Run-in heading

A level-four heading is set in italics at the start of its paragraph, like LaTeX’s \paragraph.

Run-in shortcode The paragraph shortcode does the same inside a paragraph.

This paragraph is justified and hyphenated with the {.justify} attribute, whatever the site setting, which is how a single paragraph can follow the justified class option of LaTeX while the rest of the page is set ragged right.

Tyger Tyger, burning bright,
In the forests of the night;
What immortal hand or eye,
Could frame thy fearful symmetry?

In what distant deeps or skies.
Burnt the fire of thine eyes?

A designer knows that he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away.

Antoine de Saint-Exupéry

The clearmargin shortcode above pushes this paragraph below everything that is still in the margin, like \FloatBarrier; clearpage starts a new page when printing.

Index

Index entries use the syntax of makeindex: levels separated by !, a sort key before @, cross-references with |see{…} and page ranges with |( and |). The quote character " makes the next !, @, | or " literal: {{< index `index!quote "!` >}} lists “quote !” under “index”. The index of this page:

Index

The references below are written with {{< bibliography heading="Works cited" >}} instead of the automatic list, which a handout leaves out when it has its own bibliography shortcode; all=true would list every entry of the database.


  1. This is a real footnote, written with the footnote shortcode. It is listed at the end of the page and marked with a letter, because the page also has numbered sidenotes. ↩︎

  2. Written as [^fn-classic]: the fn- prefix keeps a Markdown footnote a real footnote. ↩︎

Works cited

  1. Edward R. Tufte. The Visual Display of Quantitative Information. Graphics Press, Cheshire, Connecticut, 2001. ISBN 0-9613921-4-2.
  2. Edward R. Tufte. Envisioning Information. Graphics Press, Cheshire, Connecticut, 1990. ISBN 0-9613921-1-8.
  3. Edward R. Tufte. Visual Explanations. Graphics Press, Cheshire, Connecticut, 1997. ISBN 0-9613921-2-6.
  4. Edward R. Tufte. Beautiful Evidence. Graphics Press, LLC, first edition, May 2006. ISBN 0-9613921-7-7.
  5. Robert Bringhurst. The Elements of Typography. Hartley & Marks, 3.1 edition, 2005. ISBN 0-88179-205-5.
  6. Frank Mittelbach and Michel Goossens. The LaTeX Companion. Addison–Wesley, second edition, 2004. ISBN 0-201-36299-6.