This guide walks through everything needed to publish a site with tufte.hugo: installing the theme, the settings it reads, the front matter it understands, and the shortcodes that produce Tufte’s layouts. The README of the theme is the complete reference; this page is the tour.
The theme needs the latest Hugo release (0.169.0 or later); the standard edition is enough, since the theme ships plain CSS and needs neither Sass nor JavaScript tooling.
As a Git submodule:
hugo new site my-site &&cd my-site
git init
git submodule add https://github.com/massimo-nocentini/tufte.hugo themes/tufte.hugo
echo'theme = "tufte.hugo"' >> hugo.toml
hugo server
As a Hugo module, initialise your site as a module and import the theme:
Hugo does not merge [markup] from a theme, so three Goldmark settings must be copied into your own configuration:
[markup.goldmark.parser]wrapStandAloneImageWithinParagraph=false# images on their own line become figuresautoHeadingID=true# the default: keep it (section numbers, xref, TOC)[markup.goldmark.parser.attribute]block=true# {.sans}, {.fullwidth}, quote attribution[markup.goldmark.extensions.passthrough]# math, see "Math and Code"enable=true[markup.goldmark.extensions.passthrough.delimiters]block=[['\[','\]'],['$$','$$']]inline=[['\(','\)'],['$','$']][markup.highlight]noClasses=false# colours from the theme's syntax.css
Raw HTML can stay disabled (unsafe = false): nothing in the theme depends on it.
All parameters live under [params] and have sensible defaults. The ones you will most likely change:
Parameter
Default
Effect
subtitle
empty
Line under the site title on the home page
sections
"h2"
Start a new section at each h2, or "none"
footnotes
"sidenotes"
Turn footnotes into sidenotes, or keep "endnotes"
etBook
true
Load the ET Book web fonts
font
"etbook"
"libertinus" (Libertinus Serif, Sans, Mono) or "source" (Source Serif 4, Sans 3)
showReadingTime
true
Reading time in the post meta line
toc
false
Table of contents at the top of posts
math.enable
"auto"
Load the KaTeX stylesheet only where math appears
math.font
"katex"
"euler", "libertinus": formulas in Euler or Libertinus Math (MathML)
slides.*
see README
reveal.js options of the pages that have slides
customCSS
[]
Extra stylesheets from your assets/ folder
search.enable
false
Search box in the header and a results page
Author and social links go in [params.author] and [params.social]; comments use Giscus ([params.giscus]) or Hugo’s Disqus template, and [params] comments = false (short for [params.comments] enable = false) turns them off site-wide.
Besides the usual title (optional: a short note without one is called by its linkTitle, else “Untitled”, i18n key
untitled, and a section, book or part whose _index.md has none by its directory name, humanized, wherever a
title is shown, so no heading or link is left empty), date, tags and categories, posts may set:
subtitle, shown in the style of Tufte’s subtitles below the title;
sections, footnotes and toc, overriding the site parameters for one page (this page sets toc: true);
math: true to force the KaTeX stylesheet;
mathFont: euler to set this page’s formulas in Euler, as Euler Math does, or mathFont: libertinus;
font: libertinus to set this page’s text in Libertinus, as Libertinus does, or font: source for Adobe’s Source Serif 4 and Source Sans 3, as Source does (code is in Source Code Pro on every page but Libertinus’s);
outputs: ["html", "slides"] to show the page as reveal.js slides too, as Slides does, with the notes shortcode for speaker notes and slides: for reveal.js options;
comments: false to hide comments;
searchHidden: true to keep the page out of the site search.
Inline shortcodes go inside a paragraph, with no line breaks around them, exactly where the note or span should appear:
Tufte uses sidenotes.{{< sidenote >}}Like this one.{{< /sidenote >}} He also
uses margin notes.{{< marginnote >}}Without a number.{{< /marginnote >}}
{{< newthought >}}In his later books{{< /newthought >}}, Tufte starts …
Set a few words in {{< sans >}}Gill Sans{{< /sans >}}.
Here they are at work: a sidenote,The content of a note is Markdown: italics, code and links are all fine. a margin note,Margin notes have no number. and a few words in a sans-serif face.
For a short text, the four of them also have a one-line form, with the text as the only positional parameter (or as the named parameter text) and a self-closing />}}:
A short aside.{{< sidenote "Written on one line." />}} Another one.{{< marginnote text="Also on one line." />}}
{{< newthought "Small capitals" />}} open a thought, {{< sans "Gill Sans" />}} changes the face.
Like this: a one-line sidenoteThis note was written on one line, with its text as a positional parameter. and a one-line margin note.Written with the named parameter text. The named parameters of sidenote (number, offset, label, cite) and marginnote (offset, cite) are described in From LaTeX to Hugo.
Block shortcodes stand on lines of their own and take Markdown inside:
{{< epigraph author="Edward Tufte" cite="The Visual Display of Quantitative Information" >}}
Above all else show the data.
{{< /epigraph >}}
{{< blockquote author="Edward Tufte" cite="The Visual Display of Quantitative Information" >}}
Graphical excellence is that which gives to the viewer the greatest number of ideas in the shortest time with the least ink in the smallest space.
{{< /blockquote >}}
{{< fullwidth >}}
This paragraph spans the full width of the page.
{{< /fullwidth >}}
The rendered block quote:
Graphical excellence is that which gives to the viewer the greatest number of ideas in the shortest time with the least ink in the smallest space.
Collapsible asides use the details shortcode (the theme’s version of Hugo’s built-in one); the theme keeps them in the text column, and a Markdown footnote inside one becomes a footnote of the page. A sidenote inside one keeps its place in the page’s numbering: the marks after the block show the same numbers whether it is open or closed.
Why sidenotes rather than footnotes?
A sidenote sits next to the sentence it annotates,This numbered sidenote is inside the collapsible block. Close the block and the marks after it keep their numbers. so the reader’s eye never has to jump to the bottom of the page and back.a
A block shortcode can be indented where Markdown asks for it, in a numbered step or in a real footnote of several paragraphs: the indentation of its opening tag is removed from the text inside it.b
Write the data as a Markdown table, indented under the step:
Table 1:A table inside a numbered step.
Step
Ink
1
low
Show the code that reads it:
Listing 1:A listing inside a numbered step.
ifink>data{erase(ink)}
A self-hosted video becomes a Tufte figure, with its caption in the margin (with type="fullwidth", a figcaption in the margin column under the video, as for a full-width image):
{{< video src="flow.mp4" poster="flow.jpg" caption="Water flow, *slowed down*." >}}
(The example site ships no video file, so this one is not shown live.) Its options:
src (required) and poster resolve like figure sources: a page resource, an assets/ resource, a static/ path or a URL (also a data: URI with an image for poster, a video or audio for src);
caption takes inline Markdown, and title is the accessible label of the video (default: the caption as plain text);
type is main (default) or fullwidth;
controls is on by default, and controls="false" hides the player controls;
autoplay, loop, muted and playsinline take "true", and autoplay implies muted and playsinline;
width and height become attributes of the <video>, and class adds classes to the <figure>.
The theme leaves empty partials for you to override from your site’s layouts/_partials/ folder: head_custom.html, header_custom.html, before_content.html, after_content.html, footer_custom.html and scripts_custom.html. Stylesheets listed in params.customCSS are appended to the theme’s CSS bundle, so their rules win. The theme ships no JavaScript, except the optional site search below; scripts you put in your site’s assets/js/tufte/ folder (that folder only) are bundled, fingerprinted and loaded deferred on every page as one classic script.
On a multilingual site, the header links every page to its translations, and the head lists them as hreflang alternates. Translations for the theme’s few words, such as “Read more” or “Older posts”, are provided in English, Italian, French, German and Spanish; in any other language they fall back to English until you add your own i18n/<lang>.yaml. The short dates of the archive follow the language too (“Jan 2” in English, “2 Jan” in Italian): set archiveDateFormat under [params] to choose another Go layout.
This site has a search box in its header: type a few words, or press / to get there. The best
matches show under the box, each with the section where the words are and a few lines around them; the arrow
keys and Enter open one, and Enter on the query opens the search page,
which lists them all. Words may come in any order and with a typo (try “lagrnge”), and accents do not matter.
It is the theme’s only JavaScript, and it is off unless the site turns it on and gives the home page the
index, the searchindex output:
The results page is any page with layout: search (here content/search.md). The index is built from the
pages as they read, numbers and cross-references resolved, with the notes in the margin kept apart and math as
its TeX; searchHidden: true keeps a page out of it. Fuse.js, which does the matching, and the index load only
when someone searches.
Everything the Tufte-LaTeX classes offer has a counterpart: numbered figures
and tables with their captions in the margin, citations in the margin and a
bibliography, cross-references, lists of figures and tables, an index, and
multi-chapter books with a title page and contents. Options go under
[params.tufte] in the site configuration, or under tufte: in front
matter; tufte: {style: latex} gives a page the look of tufte-handout.
From LaTeX to Hugo maps every
LaTeX command to its shortcode, with live examples; the
handout and the
book are ports of the two
Tufte-LaTeX samples.
The theorem environments of LaTeX’s amsthm are block shortcodes:
theorem, lemma, proposition, corollary, definition, example,
remark, thm for any other kind, and proof. The note and the label are
the two positional arguments, and {{< proof of="thm:x" >}} names the
theorem it proves:
{{< lemma "Bézout" "lem:bezout" >}}
For integers $a$ and $b$ there are integers $x$ and $y$ with $ax + by = \gcd(a, b)$.
{{< /lemma >}}
Lemma1(Bézout). For integers a and b there are integers x and y with
ax+by=gcd(a,b).
Proof of Lemma 1. If a=b=0, take x=y=0. Otherwise the set of the integers
ax+by has a smallest positive element d; it divides a and b (the
remainder of a divided by d is again of that form and smaller than d, so it is 0),
and every common divisor of a and b divides d. ■
All kinds share one counter, as in the AMS templates; the options
tufte.theorems.* declare new kinds and change counters, numbering within
sections or chapters, the look of the heads and the end-of-proof symbol.
Theorems and Proofs shows them all,
with cross-references and a list of theorems.
A real footnote, referenced from inside the collapsible block, listed below the text. ↩︎
A real footnote whose second block is a listing, indented by four spaces like every continuation of a footnote.