Immaculate

Immaculate is a Jekyll theme that generates Google AMP-compliant static websites with Tufte CSS styling, built for fast-loading, typographically refined blogs. It takes Markdown posts and page files and outputs validated AMP HTML that can be served through Google's AMP CDN, with the README reporting DOMContentLoaded times under 100 ms on the leaner stylesheet. The theme is open source under the MIT license, based on the amplify project for its AMP plumbing.

What is Immaculate?

Immaculate is a Jekyll theme created by the developer behind the siawyoung/immaculate repository, combining the static-site generation of Jekyll with the editorial design of Tufte CSS and the performance constraints of Google AMP. The theme accepts standard Jekyll content — Markdown files, _config.yml settings, and Liquid templates — and produces a static HTML site that passes AMP validation. It includes the Tufte CSS stylesheet and a set of custom Liquid plugins in _plugins/shortcodes.rb to ease authoring of Tufte-style elements. The repository credits Amplify as the basis for most of the AMP-related code.

Key Features

• AMP compliance — Every output page is built to satisfy AMP HTML requirements, making the site eligible for Google's AMP CDN and its cache; typical DOMContentLoaded times are reported under 100 ms with the leaner stylesheet when served through the CDN.
• Tufte CSS integration — The theme ships with Tufte CSS, including support for sidenotes, margin notes, and full-width figures through dedicated Liquid tags.
• Custom helper tags — _plugins/shortcodes.rb provides image, youtube, sidenote, marginnote, and blockquote tags that generate AMP-compliant markup; the image and youtube tags require explicit width and height values as AMP mandates.
• Performance switch — A leaner stylesheet (lean_tufte) replaces the et-book font stack with the Palatino system stack, reducing custom font weight by roughly 160 KB and cutting typical load times from about 300 ms to 50 ms anecdotally.
• Syntax highlighting — Built-in support is included but disabled by default; uncommenting one line in _includes/styles.scss activates it.
• Optional full-width and raw modes — Both image and youtube tags accept an fw option for full-width display and a raw option to output the raw AMP tag, useful inside margin notes.

Who is it for?

Immaculate is aimed at writers and developers who publish long-form content and care about both typography and page speed.

• Bloggers and newsletter authors who want Tufte's sidenote-and-margin-note style without hand-writing HTML.
• Developers building AMP-required sites who need a Jekyll theme that produces valid AMP pages out of the box.
• Performance-focused site owners who want to serve pages through Google's AMP CDN, potentially at sub-100 ms DOMContentLoaded times.

What can you do with Immaculate?

• Write an article with sidenotes using the sidenote tag, passing a unique id and a body that supports inline HTML like emphasis and italics.
• Embed an AMP-compliant YouTube video with the youtube tag, specifying the video id, width, and height; add fw to make it full width.
• Create Tufte-style blockquotes with a footer using the blockquote tag block, which adds an attribution line below the quote.

How does Immaculate work?

To get started, clone the repository, run bundle install, and then bundle exec jekyll serve --baseurl ''. Content lives in Markdown files and standard Jekyll directories; the custom plugins process Liquid tags at build time to generate the final AMP HTML. Changing from the default to the leaner font stack only requires editing one line in _includes/styles.scss.

Pros and cons

• Pro: The theme is free under the MIT license and the source is available for modification.
• Pro: AMP compliance gives access to Google's CDN, which the README reports yields DOMContentLoaded times under 500 ms even on a simulated 2G connection.
• Con: AMP HTML forbids form elements such as checkboxes, so the Tufte CSS mechanism to toggle sidenotes and margin notes on narrow screens is currently disabled — the README explicitly asks for help emulating this without checkboxes.
• Con: The default et-book fonts add roughly 160 KB to the page; a leaner Palatino-based option is provided to reduce that weight.

FAQ

How can I use the sans-serif version of Tufte CSS with Gill Sans?

Override the font-family in the body rule inside _includes/styles.scss with your preferred stack, for example "Gill Sans". The README includes this as a supported customization.

Does Immaculate support syntax highlighting?

Yes, but the highlighting stylesheet is commented out by default to keep pages lean. Uncomment the @import 'syntax-highlighting'; line in _includes/styles.scss to enable it.

Is Immaculate free to use?

Yes, Immaculate is released under the MIT license. The repository is public and the README provides clone-and-publish instructions.

Why are sidenotes not toggleable on small screens?

AMP HTML does not allow form elements, including the checkboxes Tufte CSS uses to show or hide sidenotes at smaller widths. Immaculate's author has disabled that behavior rather than break AMP validation, and notes the issue in the README.