Figures and Tables

Main-column, margin and full-width graphics; tables that keep to the grid

Graphics belong next to the words that discuss them. Tufte CSS knows three places to put them: the main text column, the margin, and the full width of the page. tufte.hugo gives each one a shortcode, and handles plain Markdown images too.

Markdown images

A Markdown image on a line of its own becomes a figure. Its title, the quoted text after the path, becomes the caption, shown as a margin note beside the image:

From Edward Tufte, Beautiful Evidence, page 159.A table of figures from Beautiful Evidence

Without a title the image is still a figure, just without a caption. An image inside a sentence stays inline. This requires wrapStandAloneImageWithinParagraph = false in the Goldmark parser settings of your site.Otherwise Goldmark wraps every image in a paragraph and the image render hook cannot tell a figure from an inline picture.

Image paths are looked up first among the resources of the page bundle, then among the site’s global assets, and finally used as plain URLs. The image above lives in the site’s assets/images/ directory.

The figure shortcode

The figure shortcode replaces Hugo’s built-in one and accepts a type: main (the default), margin or fullwidth. Captions are Markdown:

The same page, placed with the figure shortcode. Captions may contain emphasis and links.A table of figures from Beautiful Evidence

Like Hugo’s own shortcode, it takes link (the image becomes a link), with that link’s target and rel, and loading: lazy, the default, or eager for an image at the top of a page ({{< figure src="cover.jpg" link="https://example.org/" target="_blank" rel="noopener" loading="eager" >}}).

Margin figures

A table of figures from Beautiful EvidenceA margin figure: the image and its caption sit in the margin, next to this paragraph. Small, ancillary graphics go in the margin. The marginfigure shortcode, which is the same as figure with type="margin", puts the image inside a margin note. Write it at the start of a paragraph, on the same line as the text, with inline="true", so the margin note becomes part of that paragraph. On a narrow screen it hides behind the ⊕ toggle, like any other margin note.

Keep margin figures small and simple: the margin is about a third as wide as the text column.

A Markdown image can go to the margin too, with a class attribute on the line after it: {.margin}, or its aliases {.marginfigure} and {.marginnote}. LaTeX-like attributes work on block images too: offset moves the caption of a main or full-width image and, like LaTeX’s marginfigure[offset], the whole figure of a margin image (here one baseline down, 1bl); captionpos="bottom" aligns the caption with the bottom of a main or full-width image (a margin image keeps its caption below it, and captionpos on it prints a warning); cite appends references, short and an {#fig:id} label it for the lists of figures, and numbered=false turns its number off.

A table of figures from Beautiful EvidenceA Markdown image in the margin, moved down one baseline.

Like the marginfigure shortcode without inline, a Markdown margin image stands between two paragraphs and floats into the margin beside the one that follows it, this one.

Full-width figures

Wide graphics, like time series and maps, need the full width of the page. Use fullwidthfigure, or figure with type="fullwidth"; the caption goes below the image:

A table of figures from Beautiful Evidence
A full-width figure with its caption in a figcaption.

Tables

Markdown tables are wrapped in a div.table-wrapper, which scrolls horizontally on narrow screens instead of breaking the layout. Column alignment is kept:

BookYearSubject
The Visual Display of Quantitative Information1983Statistical graphics and data-ink
Envisioning Information1990Maps, layering and small multiples
Visual Explanations1997Images of cause, motion and evidence
Beautiful Evidence2006Sparklines, mapped pictures, analytic design
Seeing with Fresh Eyes2020Meaning, space, data, truth

Tufte’s tables are sparse: few rules, no shading, and numbers aligned on the right so that their digits line up.Alignment comes from the colons in the delimiter row: :-- left, :-: centre, --: right.

A table can take the full width of the page with the fullwidth attribute on the line after it. This one lists powers, factorials, Fibonacci numbers FnF_n, primes pnp_n and triangular numbers TnT_n; its header cells are inline math:

nnn2n^2n3n^3n4n^42n2^n3n3^nn!n!FnF_npnp_nTnT_n
1111231121
24816492133
3927818276256
416642561681243710
5251256253224312051115
63621612966472972081321
101001000100001024590493628800552955

Video and other embeds

The youtube shortcode embeds a video through YouTube’s privacy-enhanced domain, inside the iframe-wrapper that keeps its aspect ratio at every screen width:

It takes the parameters of Hugo’s own youtube shortcode: start and end (in seconds), autoplay, mute, loop, controls, allowFullScreen, loading, title and class. This copy starts at the thirtieth second and hides the player controls:

For any other embeddable page there is the iframe shortcode, with src, title and an optional ratio. Here it embeds a map of Florence at a 4:3 ratio:

Inside a fullwidth block an embed spans the whole page width, margin included, as any other content of the block does:

A self-hosted video uses the video shortcode, which makes a Tufte figure with the caption in the margin (see the theme guide for its options). This example site ships no video file, so it is not shown live here:

{{< video src="flow.mp4" poster="flow.jpg" caption="Water flow, *slowed down*." >}}