Skip to content

This piece is a draft.

Writing Feed
Writing Feed

Tufte-Inspired Elements

Teddy Warner's GitHub profile picture Teddy Warner | Mar 2026 | 9–11 mins

The English language becomes ugly and inaccurate because our thoughts are foolish, but the slovenliness of our language makes it easier for us to have foolish thoughts.

George Orwell, "Politics and the English Language"

For a successful technology, reality must take precedence over public relations, for Nature cannot be fooled.

Richard P. Feynman, "What Do You Care What Other People Think?"

I do not paint things, I paint only the differences between things.

Henri Matisse, Henri Matisse Dessins: themes et variations (Paris, 1943), 37

In his later books, Tufte starts each section with a bit of vertical space, a non-indented paragraph, and the first few words of the sentence set in small caps. This is the newthought element, used at the start of new sections to signal a shift in topic without the disruption of a heading. Vertical spacing is accomplished naturally through markdown paragraph breaks.

This paragraph demonstrates how body text renders. Notice how the text feels different from a typical sans-serif web fontET Book is based on Bembo, originally designed by Francesco Griffo in 1495. The digital version was created by Dmitry Krasny, Bonnie Scranton, and Edward Tufte. – there is a warmth and humanity to the letterforms that makes extended reading comfortable.

Everything should be made as simple as possible, but no simpler.

Sidenotes and Margin Notes

One of the most distinctive features of Tufte’s style is his extensive use of sidenotes. Sidenotes are like footnotes, except they don’t force the reader to jump their eye to the bottom of the pageThis is a sidenote. On large screens it appears in the margin to the right. On small screens, tap the number to reveal it inline.. Instead, they display off to the side in the margin, keeping related but secondary information close to the text that references it.

If you want a note without the superscript number, you can use a margin note insteadThis is a margin note. Notice there is no number preceding it – just a small icon on small screens to toggle visibility.. Margin notes are useful for asides, definitions, or contextual information that relates to the adjacent text but doesn’t require a formal citation reference.

The goal is to present related but not necessary information as close as possible to the text that references it. At the same time, this secondary information should stay out of the way of the eye, not interfering with the progression of ideas in the main text.

Figures

Tufte emphasizes tight integration of graphics with text. Data, graphs, and figures are kept with the text that discusses themMargin figureA small image placed in the margin, adjacent to the text that references it.. On the web, that means readability of graphics and their accompanying text without extra clicks or scrolling.

Standard figures are constrained to the main columnA standard figure with a margin description. This note collapses to a circle-plus icon on small screens.:

A standard figure

For images that need more space, use the fullwidth classFullwidth figures expand into the TOC sidebar area, giving more:

A fullwidth figure spans the entire content area

Figure Grids

Multiple images can be laid out in flexible grids. Images share heights and distribute width automatically, adjusting for varying aspect ratios.

2x1 Grid:Images in a grid automatically share the same row height while dynamically adjusting their widths based on aspect ratio.

Grid image 1 Grid image 2

3x1 Grid:

Grid image 3 Grid image 4 Grid image 5

2x2 Grid:

Grid image 6 Grid image 7 Grid image 8 Grid image 9

Links in this design match the body text in color and do not change on mouseover or when clicked. They are underlined with a subtle, thin line – the most widely recognized indicator of clickable text. Here is a link that demonstrates this styling. The underline becomes slightly more prominent on hover, but the text color remains unchanged throughout all states: unvisited, visited, hover, and active.

This approach keeps the page visually calm. Traditional blue links create visual noise that disrupts the reading experienceTufte’s principle: minimize non-data ink. Blue link text is non-data ink that adds visual clutter without aiding comprehension., particularly in text-heavy pages where many references appear. The underline alone is sufficient to signal interactivity.

Code

Technical jargon, programming language terms, and code samples use monospace formatting. Code blocks use syntax highlighting provided by Material’s native Pygments integration.

tufte_elements.py
def on_page_markdown(markdown, page, config, files, **kwargs):
    """Process Tufte shorthand syntax in markdown."""
    src_path = page.file.src_path
    if not (src_path.startswith('projects/') or src_path.startswith('writings/')):
        return markdown
    return process_elements(markdown)
mkdocs.yml
theme:
  features:
    - content.code.annotate # (1)
  1. Code annotations are also styled monochromatic.

Admonitions

Abstract

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus.

A Note

Notes provide additional context without interrupting the flow.

Information

Informational callout with supporting details.

Helpful Tip

A useful suggestion for the reader.

Warning

Something to be cautious about.

Danger

Critical information that requires immediate attention.

Inline Note

This note floats to the left of the following content, useful for short asides that relate to adjacent text.

Inline End

This note floats to the right, creating a two-column layout with the adjacent note.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa. Clear the inline admonitions with some body text.

Collapsible Tip

Click the title to expand. Collapsible admonitions use the same styling.

Collapsible Warning

Warnings and other types maintain consistent appearance across states.

Buttons

Buttons are styled to be minimal and sleek, consistent with the monochromatic palette.

Primary Button Outline Button

Tables

Standard formatted tables receive refined typography and subtle horizontal rules.

Method Description Status
GET Fetch resource Supported
PUT Update resource Supported
DELETE Delete resource Restricted
POST Create resource Supported

Bill of Materials

Long BOM tables are wrapped in a scrollable container with a sticky header for easy navigation. Use a bom-table wrapper:

Qty Description Cost Link Notes
14 Breadboard $112 link Standard solderless
10 1k resistor – link 1/4W
9 10k resistor – link 1/4W
24 470 resistor – link 1/4W
6 0.01uF capacitor $1.20 link Ceramic
16 0.1uF capacitor $3.00 link Ceramic
4 555 timer IC $0.63 link NE555
2 74LS00 NAND gate $0.76 link Quad
5 74LS04 Hex inverter $0.87 link
3 74LS08 AND gate $0.72 link Quad
8 74LS173 D register $1.45 link 4-bit
2 74189 RAM $9.90 link 64-bit
6 74LS245 transceiver $1.26 link Octal
3 28C16 EEPROM $11.85 link
44 Red LED – link 5mm
8 Yellow LED – link 5mm
12 Green LED – link 5mm
4 7-segment display $4.36 link Common cathode
1 22 AWG wire $29.95 link Solid core

Lists

Ordered List

  1. First item with some description text
  2. Second item that continues the sequence
  3. Third item demonstrating consistent spacing
    1. Nested items maintain hierarchy
    2. With proper indentation

Unordered List

  • Item one describing a feature
  • Item two with a brief explanation
  • Item three continuing the pattern
    • Nested sub-items
    • Are properly indented

Task List

  • Completed task with strikethrough indicator
  • Another finished item
    • Nested completed sub-task
    • Nested incomplete sub-task
  • Remaining work to be done

Definition List

Term One

A clear definition with proper indentation and spacing, maintaining readability across multiple lines.

Term Two

Another definition that demonstrates consistent formatting throughout the definition list structure.

Content Tabs

Example Configuration
theme:
  features:
    - content.code.annotate
Example Script
import mkdocs
config = mkdocs.config.load_config()

!!! note "A Note"
    Content goes here.

LaTeX / Math

Inline math: The quadratic formula is \(x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}\) and can be derived by completing the square.

Display math:

\[W_{counter} = k \cdot \frac{W_{gondola}}{2}\]

where \(k \approx 0.75\text{-}0.85\) gives good results.

\[\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}\]

YouTube Embed

Twitter / X Embed

Iframe Embed

Markdown Shorthand Reference

The Tufte shorthand syntax is processed by tufte_elements.py before rendering:

Element Syntax
Newthought <span class="newthought"> Text </span>
Sidenote <label for="sn-4" class="margin-toggle sidenote-number"></label><input type="checkbox" id="sn-4" class="margin-toggle"/><span class="sidenote"> Note text </span>
Margin note <input type="checkbox" id="mn-9" class="margin-toggle"/><label for="mn-9" class="margin-toggle"><i class="fa-solid fa-circle-plus"></i></label><span class="marginnote"> Note text </span>
Margin figure <input type="checkbox" id="mn-11" class="margin-toggle"/><label for="mn-11" class="margin-toggle"><i class="fa-solid fa-circle-plus"></i></label><span class="marginfigure"><span class="caption"> ![alt](url) + caption </span></span>
Epigraph {.epigraph} + blockquote lines + {/.epigraph}
Fullwidth {.fullwidth} … {/.fullwidth}
Figure grid <div class="figure-grid grid-2x1"> … </div>
Carousel {.carousel}path/to/folder{/.carousel}
BOM table <div class="bom-table" markdown> … </div>
Embed frame <div class="embed-frame"><div class="embed-inner"> iframe </div></div>

Comments

Copyright © 2026 Teddy Warner