Twelvety

Twelvety is an Eleventy starter project that pre-configures a full build pipeline — Sass/PostCSS styling, Browserify/Babel scripting, minification, critical CSS inlining, and responsive images — so you can focus on writing templates and content. It's a boilerplate for static sites, not a theme: you get the tools and structure but design your own pages.

What is Twelvety?

Twelvety is an open-source Eleventy starter project built to be fast, created by Greg Ives and available on GitHub. As input it takes Eleventy templates that use Twelvety's paired shortcodes for styles, scripts, and images; as output it produces a static site with minified HTML, CSS, and JS, content-hashed asset filenames, and inline critical CSS. The project stores its configuration in .twelvety.js and its build logic in the utils directory, which you can safely ignore when building a site.

Key Features

• Component architecture — Co-locate markup, Sass, and JavaScript in the same template file using the stylesheet, javascript, and append paired shortcodes, scoped to each page by chunk.
• Sass/PostCSS pipeline — Compile Sass with dart-sass, run it through PostCSS with PostCSS Preset Env and Autoprefixer, then minify with clean-css in production or beautify with JS Beautifier in development.
• Browserify and Babel JavaScript pipeline — Use require('modules') in the browser, transpile with Babel, and minify with Uglify in production.
• Page-specific CSS and JS — The styles and script shortcodes gather only the code for the current page.url chunk by default, so each page ships only the assets it needs.
• Responsive picture shortcode — Takes src, alt, optional sizes (defaults to 90vw), and loading (defaults to lazy), and outputs AVIF, WebP, and JPEG sources with a calculated background color and padding-bottom to avoid layout shift.
• Content-hashed assets — The asset shortcode saves any captured text or buffer to a hashed filename in the assets directory inside the output directory.
• Critical CSS extraction — Uses eleventy-critical-css to extract and inline critical-path CSS on every page.
• HTML formatting transform — The format transform beautifies HTML with JS Beautifier in development and minifies it with HTMLMinifier in production.

Who is it for?

• Eleventy developers who want a ready-made build setup — Skip wiring up PostCSS, Babel, minification, and image handling yourself; Twelvety provides them as configurable shortcodes.
• Front-end developers who prefer component-based workflows — Write markup, styles, and scripts together in one file, then let Twelvety extract, bundle, and minify them per page.
• Developers deploying static sites to Netlify — Use the one-click deploy button to clone the repository to GitHub and deploy it to Netlify without manual configuration.

What can you do with Twelvety?

• Build a content site — Use the markdown paired shortcode to include Markdown files and rely on the automatic picture shortcode transformation so every image in Markdown becomes a responsive picture element.
• Create a production-ready static site — Run npm run build to generate minified, content-hashed assets and inline critical CSS, ready for any static host.
• Customize the build pipeline — Edit .twelvety.js to change the Sass style (including indented syntax), enable AVIF output, or adjust image sizes and cache behavior.

How does Twelvety work?

Install dependencies with npm install, then run npm run serve for a development server with live-reload, npm run build for production output, or npm run clean to clear the output folder and the Twelvety cache (.twelvety.cache). The build logic lives in the utils folder, and project-specific settings go in .twelvety.js.

FAQ

How do I deploy Twelvety to Netlify?

Click the 'Deploy to Netlify' button in the README. Netlify will clone the Twelvety repository to your GitHub account (with your permission), add the new repository to your Netlify account, and deploy it. The repository also has a 'Use this template' button on GitHub for creating your own copy.

Does Twelvety support responsive images?

Yes. The picture shortcode outputs AVIF, WebP, and JPEG sources with configurable sizes and native lazy loading. AVIF is disabled by default because it makes builds slow; enable it in .twelvety.js. The shortcode also computes the average color of the image to use as a placeholder while loading.

Why is my CSS not being inlined in the head?

The styles shortcode must appear after all stylesheet paired shortcodes in the template. To move the collected CSS into the head, wrap it in the append paired shortcode, which a transform uses with jsdom to relocate the content to the given selector. The same pattern works for scripts, though scripts are usually fine at the end of body.

How do I clear the image cache?

Delete the .twelvety.cache file (a JSON file) or run npm run clean, which also deletes the output directory. If you delete the output directory but keep the cache, things will break, so always clear both together.

Can I use Twelvety with JavaScript modules?

Yes, through Browserify. You can require('modules') inside the javascript paired shortcode, and Twelvety bundles them with Browserify, transpiles with Babel, and minifies with Uglify in production. The output is wrapped in an IIFE so your variables don't pollute the global scope.