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:

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:
figure shortcode. Captions may contain emphasis and links.
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 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 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:

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:
| Book | Year | Subject |
|---|---|---|
| The Visual Display of Quantitative Information | 1983 | Statistical graphics and data-ink |
| Envisioning Information | 1990 | Maps, layering and small multiples |
| Visual Explanations | 1997 | Images of cause, motion and evidence |
| Beautiful Evidence | 2006 | Sparklines, mapped pictures, analytic design |
| Seeing with Fresh Eyes | 2020 | Meaning, 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 , primes and triangular numbers ; its header cells are inline math:
| 1 | 1 | 1 | 1 | 2 | 3 | 1 | 1 | 2 | 1 |
| 2 | 4 | 8 | 16 | 4 | 9 | 2 | 1 | 3 | 3 |
| 3 | 9 | 27 | 81 | 8 | 27 | 6 | 2 | 5 | 6 |
| 4 | 16 | 64 | 256 | 16 | 81 | 24 | 3 | 7 | 10 |
| 5 | 25 | 125 | 625 | 32 | 243 | 120 | 5 | 11 | 15 |
| 6 | 36 | 216 | 1296 | 64 | 729 | 720 | 8 | 13 | 21 |
| 10 | 100 | 1000 | 10000 | 1024 | 59049 | 3628800 | 55 | 29 | 55 |
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*." >}}