Customizing an Eleventy theme: where the build breaks
A customized theme rarely breaks in just one place. First the layout is edited, then markup is appended directly to the built file, then a data template is renamed — and the next build returns some pages empty or fails while resolving a layout.
From the outside it looks accidental, but in essence it is accumulated divergence between templates and layouts.
The most common source of build errors when customizing an Eleventy theme is a broken inheritance chain. When another layout level is added on top of the theme, child pages start inheriting it instead of the original one.
If the intermediate template does not declare a parent, or an overridden block does not call the base one, pages lose the header, footer, and descriptions entirely — while the build completes without a single warning.
Second — manual edits in built files. The output directory is overwritten on every run, so an edit lasts exactly until the next build: locally everything looks working, but on the live site the old version returns. Debugging this is hard because the source files and what is served to the visitor diverge.
Third — broken pages from lost connections. A page outside a collection does not get a URL, a menu link leads nowhere, and a data template with a typo in a field name returns an empty list where a catalog was expected. The error does not surface until a specific section is viewed.
The publication bottleneck is a full site rebuild just to edit one block: the more templates there are, the more noticeable the pause between a change and the finished page.
Frequent build mode does not always help: it does not track data template dependencies, so a stale fragment remains in the output. We'll look at how this is addressed.
Measurable effect: build, page weight, stability
A carefully configured theme is measured not by "it looks tidier" but by four values: full build time, the share of pages published without manual edits, the delivery weight on mobile, and the number of developer requests.
In Eleventy, each of them depends on how templates, collections, and data are structured, so we capture these values before and after the work.
Build time grows from two habits: page lists are assembled manually, and templates recompute the same fragments every time.
When sections are described as collections with explicit sorting rules, and the menu, cards, and footer are extracted into reusable fragments, extra passes over files disappear.
A full build fits into tens of seconds instead of minutes, and editing one item does not touch the entire site.
Page weight is reduced by including styles and utility scripts precisely, and processing images directly at build time — a page gets exactly the set of resources it needs.
The catalog and landing pages deliver a many-times smaller volume on mobile, and this is visible in rendering speed.
Publication stability rests on data: content lives in separate files with a verifiable structure, and typical blocks are described once.
An editor changes text and parameters without touching the markup, and if a field is filled in incorrectly, the build stops with a clear error instead of publishing a page with an empty block.
The share of pages without developer intervention reaches the majority, and the number of "please fix it on the site" requests drops severalfold.
Theme setup options: from ready-made to custom
In Eleventy, a theme is not a monolith but a combination of layouts, includes, collections, and data processing rules. That is why the approach is determined by one thing: how closely the content structure matches the standard one built into the theme by its author.
The boundary runs along the number of page types and data sources: one source and 3–5 types fit within a ready-made theme, while ten types, a custom grid, and multilingual support require a custom one. The later the switch to the next option is made, the more expensive it becomes.
| Option | When it fits | Limitations and maintenance cost |
|---|---|---|
| Ready-made theme | A typical content site: blog, documentation, a set of landing pages | Templates and data are defined by the author; deep edits mean rewriting layouts, and updates conflict with local changes |
| Modifying a ready-made theme's templates | The theme matches the task by 70–80%, and launch needs to be accelerated | Edits spread across inherited templates, coupling grows; theme updates are migrated manually |
| Custom theme | Dozens of page types, a custom design language, multiple languages or brands | Longer start, requires its own conventions for layouts, collections, and data processing |
| Separate interface build | One set of components goes into several sites or themes | More complex build: synchronizing component versions and controlling compatibility between projects |
Eleventy setup stages: from audit to handover
We start the work not with markup edits but with an inventory: collections and layouts, the structure of the data directory, global filters and shortcodes, and the build config.
Then we arrange the stages so that every change is verifiable, rather than "we fixed it and we'll see."
-
Template audit. We break down the template tree and markup duplication, and look at which collections are assembled from front matter and which come from external sources. The result is a template map and a list of places that break when a new page type is added.
-
Data schema. We fix front matter fields, the data cascade, and merge rules at the directory level: what is inherited by a folder, and what is overridden by a page. The schema is described explicitly, so new content is added without template edits.
-
Build setup. We reduce the config to a single source of truth: paths, collections with sorting, pagination, page URLs, and processing of styles and images. Draft mode cuts local builds down to seconds.
-
Theme customization. We split markup into reusable blocks, and typography and the grid into variables. Changing the logo, palette, or menu structure stops being an edit across a dozen files.
-
Regression check. We capture reference pages before changes, then compare markup, metadata, headings, and the sitemap afterwards. The build fails on a broken link or a data schema mismatch, not in production.
-
Project handover. We hand over the repository with history, the config, schemas, instructions for adding pages, and setup notes. Training is conducted on a real editor task.
What the client receives: files and documentation
Project handover is not an archive with source files but a set of artifacts that make it possible to reproduce the build on a clean machine and make an edit without figuring out the architecture from scratch.
Below is the fixed composition: it also serves as an acceptance checklist, where each item either is in the repository or has a written explanation of why it is not needed.
- Build configurations: Eleventy settings, the list of plugins and transformations, separate sets of parameters for the local environment and production — the build produces the same result on any machine.
- Structure schema: a map of template, layout, collection, and data directories with an explanation of where each page block comes from.
- Template documentation: the purpose of each layout, required metadata fields at the top of the file, inheritance rules, and compatible block combinations.
- Edit and version policy: how a branch is formatted, what is checked before merging, how releases are numbered, and how to roll back to the previous build.
- Publication policy: what goes to production automatically, what requires manual confirmation, and where to view the build log.
- Access and roles: who edits templates, who only handles content, who publishes; keys and tokens are in a secrets store, not in the repository.
- Editor instructions: how to add a page or entry, which fields are required, and where to check the result before publishing.
The handover concludes with a short acceptance test: running the build in a clean environment, checking routes, forms, and permission separation — we close any discrepancies before the project goes to your team.
From practice: migrating a catalog to a static build
A catalog with several thousand cards lived on a dynamic platform: each page was assembled by a database query, the cache warmed up after every edit, and publishing a single price dragged along a rebuild of the entire category tree.
Managers waited tens of minutes for deployments and could not say which version of a page was being served to a customer right now.
What it was like before the migration
Peak seasonal load brought the catalog down: pages with filters hit the memory limit, search locked the table, and the share of error responses during peak hours reached several percent.
Rollback after an unsuccessful release took hours — builds were assembled manually, and the cause of the failure was sought by sifting through files and logs.
What it became after
The catalog was moved to a static build: templates, data, and media live in the repository, pages are generated in advance, and a ready set of files is shipped to the server.
The build is handled by Eleventy, so a full run across 4,800 cards takes about two minutes, and editing one card rebuilds only its dependencies. Page response time dropped from seconds to tens of milliseconds, and deploying changes was reduced from half an hour to three minutes.
The failure class changed: the server no longer depends on the database at request time, so traffic spikes, slow queries, and search failures are no longer causes of unavailability.
Returning to the previous state means switching to the previous set of files, in less than a minute, without manually assembling archives.
How does customizing an Eleventy theme differ from new development?
The fork is simple: either only the markup changes, or the content model changes. If entry types, collections, and the relationships between them remain, and only the layout and individual blocks diverge, customizing an Eleventy theme is faster and safer.
We edit layouts and include fragments, add computed fields to the build configuration, and leave the data structure untouched — existing URLs stay in place.
| Option | When it fits | Limitations |
|---|---|---|
| Modifying the current theme | Markup and styles change, content model stays the same | You inherit someone else's decisions: template duplicates, non-obvious names, extra dependencies |
| Rewriting the template layer | New page types have appeared, collections and data relationships have changed | Requires layouts and checks for all existing URLs, longer start |
| New template layer with content migration | The theme is unsupported, but content and URLs must be preserved | Requires a redirect map and verification of the URL structure |
Effort estimation is based not on the number of pages but on the number of affected templates and connection points. We count how many layouts depend on current collections, how many URLs need to be preserved, and how many page types will appear.
If edits touch more than half of the templates, or the content model has already diverged from the markup, rewriting pays for itself in the very first iteration of improvements.
Customization preserves someone else's decisions: they have to be worked around, and every subsequent edit costs more. After rewriting, templates are assembled from small repeatable blocks, and data relationships are described explicitly.
We lock in the choice of approach before the start — then timelines and scope are clear immediately, rather than being clarified along the way.
Common technical doubts before starting work
The same questions usually come up before the start: what will happen to URLs after migration, whether the editor can change content independently, how third-party code coexists, and whether the theme will survive an Eleventy update. We answer briefly so that a separate meeting is not needed.
Will page URLs be preserved during migration?
Yes. We describe the correspondence between old and new paths before launch: for each significant page we set a permanent link and make sure the redirect chain is no longer than one hop. The URL map goes into the report together with the crawl check results.
Will we be able to edit content without a developer?
Yes, that is part of the work. We move texts, images, and metadata into page data, and define the structure with content collections. The editor changes everything in a familiar interface, and the build itself rebuilds only the affected pages.
What should be done with third-party code in the project?
We sort it out: we mark modules that are actually used, and the legacy of previous edits. We connect the working ones to the new template structure, and remove the unnecessary ones one by one, each time checking that the build and pages have not changed.
How are accesses handed over?
We set them up on your accounts, not personal ones: repository, hosting, domain, form and analytics services. We work via an invitation with the required role — revocable in one step, with keys stored in protected environment variables.
What about theme updates?
We keep custom templates and styles separate from the base ones so that a new version does not overwrite edits. We put updates in a separate branch, run the build, and release only after checking.
Let's discuss the task: what to send and how the work will proceed
To come back with an estimate and a plan, rather than ten clarifying questions a week later, one email with the initial details is enough for us. Below is what to put in it: it is enough to understand the scope of Eleventy theme customization and the order of work.
- A link to the current site or theme repository: what has already been built, which templates are being edited, what is being rewritten from scratch.
- Designs in a design file or at least the page structure: blocks, their states, behavior at different screen widths.
- A list of content types and templates that need to be created for them, including repeating cards and lists.
- Where the build lives: hosting, domain, build pipeline, and who on your team holds the accesses.
- Requirements for forms and integrations with external systems: content editor, request tracking, search, analytics, multilingual support.
- Constraints and acceptance rules: supported browsers, markup and metadata requirements, and who accepts the result.
Once we receive this, we come back with an estimate and a plan: a list of stages, their order, what is needed from your side at each step, and where the approval points are.
The order of work is usually as follows: review of the initial details and the current theme, agreement on the template structure, customization and styling, filling with test content, checking on real builds, and handover with documentation.
If some data is missing, that's fine — we'll fill it in on a call, and the estimate will not shift by weeks because of it.
Describe the task in free form and attach what you already have at hand. We will review the materials, ask substantive questions, and come back with an estimate and a work plan.
