How the build works
You can run the blog for years without reading this chapter. It’s here for when you want to change behavior, not content.
The two files that matter
content/content.11tydata.js
Data applied to every file under content/. This is where the publishing rules live:
- permalink — built from the file’s path (
content/2026/07/x.md→/2026/07/x/), orfalse(don’t build) when the article isn’t live. - isLive — an article is live unless
published: falseor itsdateis in the future. - coverUrl / editUrl — computed per article for templates.
eleventy.config.js
Everything else, in one file (~250 lines):
| Section | Does |
|---|---|
| Markdown setup | markdown-it + anchors, footnotes, task lists |
| Collections | posts (all live articles, newest first), tagPages (tag × page-of-20 chunks), archiveMonths |
| Filters | dates, reading time, related-posts scoring, TOC extraction, search index JSON |
| Preprocessor | rewrites  to the article’s absolute path before rendering |
| Feed plugin | generates /rss.xml |
| Syntax highlighting | Prism at build time |
| Passthrough | static/ → site root; content/**/images/ → /YYYY/MM/images/ |
Templates
Nunjucks files, thin by design:
_includes/layouts/base.njk ← <head>, meta tags, header, footer, search overlay
_includes/layouts/post.njk ← article page: TOC, body, prev/next, related
_includes/layouts/page.njk ← standalone pages
_includes/partials/post-card.njk ← the card used on every listing
index.njk / archive.njk / month.njk / tags.njk / tag.njk / search.njk / 404.njk
sitemap.njk / search-index.njk ← XML and JSON outputs
Site-wide values (title, URL, author, GitHub links) are in _data/site.js and available in every template as site.*.
Design constraints to preserve
- Convention over configuration. The file’s location is its URL; the frontmatter is its metadata. Resist adding options.
- Publishing must never require code. If a new feature would make authors touch templates per-article, it’s the wrong design.
- Build-time only. No client-side rendering of content, no external services. The one exception is the small vanilla-JS layer for theme, search, and copy buttons in
static/js/.