Tufte Project Pages

Generate elegant tufte-esque webpages from markdown files. This project is inspired by and uses styling from tufte.css. This utility can be used to generate pages for research projects or for static blog posts.

This is a workflow I have duct-taped together for my own use. Please use it with care and caution. If you do use this, I would love to hear from you.

To make contributions or simply suggest additional features, please open a PR or issue. I will do my best to review and maintain this work.

Examples

Included is a file examples/sample.md that is used to generate the example project page linked above. Assets to generate this webpage are included in the assets folder. Examining the structure of this sample could be a useful starting point for making your own website.

examples/blog.md shows how the same template could be used to generate a blog page. This mostly has to do with how frontmatter is structured and handled. Take a look at the example if you want to see how it works. The steps for generating the html are the same as other examples. This is an actual blog page generated using this template.

Screenshots

I've broken out the screenshots into a separate file in the examples directory.

Writing using this Template

Currently, this template supports a few elements: sections, lists, image figures, video figures, iframe figures, text, code snippets, sidenotes, markdown tables.

Sections & Text

You can create a new section using the following:

## Section Name

Text that is part of this very interesting section

Headings get a slug id (## Source Code & Documentation -> id="source-code-documentation") so you can deep-link to them.

Figures

Figures use markdown's image syntax with a small attribute block. The text inside [...] is the caption, the path inside (...) is the source, and {...} after the image carries any options.

![_Figure 1._ A caption that supports _italics_, **bold**, & [links](https://example.com).](path/to/image-or-video){alt="Figure 1"}

The caption is rendered on the right-hand margin when the window is wide enough, and underneath the figure in narrow aspect ratios (e.g. mobile). The caption supports inline markdown (links, emphasis, code).

Depending on the file type specified (based on extension) the figure will render an image or video using html <img> or <video> tags.

For a full-width figure, add the .fullwidth class:

![…caption…](path/to/image.png){.fullwidth alt="Figure 1"}

If you leave the caption empty (![](src)), the figure renders without the margin-note widget.

iFrames

Figures can also be iframes by setting type=iframe:

![…caption…](https://link_to_iframe){type=iframe .fullwidth}

Sidenotes

One of the nice things about Tufte's layout is extensive use of sidenotes. To make a sidenote in markdown, simply specify the following inline:

Some text that wants to make a {=reference | text that explains the reference=} that helps provide the reader context

The part before the pipe (|) is the highlighted phrase that triggers the note; the part after is the note itself. Both sides accept inline markdown. Numbering is automatic.

Code Snippets

Code snippets are automatically created from any text within ``` ``` tick marks.

Tables

Just write a regular markdown table. The renderer wraps it in a .table-wrapper div so the responsive styling kicks in:

| Resolution | Training Time | Number of Splats |
| ---------- | ------------- | ---------------- |
| 232x128    | 3m 38s        | 662,428          |

Frontmatter

To generate the title, author list, affiliations and links the markdown must begin with some frontmatter in the following format:

title: "FunkyName: Actual Title of Paper"
venue: to appear at ACM Conf 2042
award: Test of Time Award
authors:

- name: "Jay Doe"
  affiliation: "University University"
  link: "link.to.jay.doe.website"
- name: "Jurgen Doe"
  affiliation: "University University" # note numbering for multiple common affiliations is done automatically. Currently only one affiliation per author is supported.
- name: "Jose Doe"
  affiliation: "Industry Industry"
- name: "Jamie Doe"
  affiliation: "University University"
  links:
  preprint: https://link-to-arXiv
  video: https://link-to-video
  publication: null # note null values will appear greyed out
  code: null # note null values will appear greyed out

links can contain any key/value pairs. The key in the yaml will be the text that is rendered on screen, and the value is what the text will link to. If an entry has a null value, it will be rendered in grey, linking to nothing.

This project uses python-frontmatter to do extract data from the frontmatter portion of the markdown.

Generating HTML

First set up your python environment. I prefer using uv. Use uv sync, or use pip to install marko, python-frontmatter & pydantic.

To generate run uv run scripts/generate.py <path-to-markdown> this will generate an html file with the same name as the markdown file. To override, pass the filename using --name, i.e. uv run scripts/generate.py <path-to-markdown> --name output. To pick a destination folder use --out-dir.

If you want to sanity-check that rendered pages still match the committed reference HTML, run bash scripts/verify.sh.

CSS

The styling for generated web pages is in style/tufte.css based on a slightly modified stylesheet from tufte-css. Modifying this will allow you to make adjustments to the resulting webpage. Look at the tufte-css website to see how this is structured.

License

Released under the MIT license.