English for Eleventy (11ty) Developers
Vocabulary for developers using Eleventy, the simple static site generator — templates, data cascade, collections, and shortcodes — for teams who value plain-language explanations of a minimal build tool.
Eleventy (often written 11ty) is a static site generator that deliberately avoids a client-side JavaScript framework — it just takes templates and data and outputs plain HTML. Its appeal is simplicity, so the vocabulary around it tends to be simpler too: “data cascade,” “collections,” “shortcodes.” Still, explaining these precisely in English matters when onboarding a new contributor or writing documentation. This guide covers the terms.
Core Philosophy
Zero client-side JavaScript by default — Eleventy ships no framework runtime to the browser unless you deliberately add one; output is plain HTML and CSS unless you opt into more. “We chose Eleventy specifically because the marketing site doesn’t need any client-side framework — plain HTML loads instantly and there’s nothing to hydrate.”
Template language agnostic — Eleventy supports multiple templating languages (Nunjucks, Liquid, markdown, JavaScript templates) in the same project, rather than locking you into one syntax.
“Our layouts are in Nunjucks, but content authors write in plain markdown — Eleventy handles both without any extra configuration.”
The Data Cascade
Data Cascade
The data cascade is Eleventy’s layered system for supplying data to templates — global data files, directory data files, front matter, and computed data all combine, with more specific sources overriding more general ones.
“The page’s title comes from its own front matter, but its layout and default author come from a directory data file further up the cascade.”
Front Matter
Front matter is the YAML block at the top of a template file defining page-specific data — layout, title, tags, and any custom fields.
“Every blog post’s front matter sets its
tagsanddate— that’s what our collections use to group and sort posts.”
Directory Data File
A directory data file (like posts.11tydata.js) applies shared data to every template inside that directory, without repeating it in each file’s front matter.
“Instead of copying the same
layoutandpermalinkpattern into every post’s front matter, we set it once in the directory data file for the posts folder.”
Computed Data
Computed data is data derived from other data at build time — for example, generating an excerpt from a post’s content rather than hand-writing it.
“We added computed data that auto-generates a reading-time estimate from each post’s word count, so authors don’t calculate it manually.”
Collections
Collection — a named group of content items, either automatically created from a shared tag or explicitly configured, used to build listing pages like a blog index or a tag archive.
“The
postscollection includes every file taggedpost, sorted by date — that’s what powers our blog index page.”
Pagination — Eleventy’s built-in mechanism for splitting a large collection across multiple output pages (or generating one page per item in a collection).
“We used pagination to generate one tag-archive page per tag automatically, instead of hand-building a page for each one.”
Templating Vocabulary
Shortcode — a reusable snippet you can call from within any template, similar to a function, used to avoid repeating markup (for example, an embedded YouTube video).
“We wrote a
{% youtube %}shortcode so authors just pass a video ID instead of pasting the full embed markup every time.”
Layout chaining — nesting one layout inside another (a post layout wrapping content, itself wrapped by a base layout), so shared structure isn’t duplicated.
“Our post layout handles the article-specific wrapper, and it in turn extends the base layout for the header and footer — that’s layout chaining.”
Filter — a function that transforms a value within a template, such as formatting a date or truncating a string, called with a pipe syntax in Nunjucks or Liquid.
“We wrote a custom
readableDatefilter so every template formats dates the same way, instead of repeating date-formatting logic everywhere.”
Build and Output Vocabulary
Passthrough copy — telling Eleventy to copy certain files or folders (images, CSS, fonts) directly to the output directory without processing them as templates.
“CSS and images are passthrough copied — Eleventy doesn’t try to template them, it just copies them straight to the output folder.”
Incremental build — Eleventy’s --incremental flag rebuilds only files affected by a change during local development, speeding up the feedback loop.
Explaining Eleventy’s Simplicity to a Team
| Situation | Phrase |
|---|---|
| Justifying the choice for a content-heavy site | ”We don’t need any client-side interactivity here — Eleventy outputs plain HTML, which means faster load times and one less framework to maintain.” |
| Explaining the data cascade to a new contributor | ”Front matter on the page always wins, but shared defaults come from the directory data file — check both before assuming a setting is missing.” |
| Describing a shortcode | ”Instead of pasting the embed code every time, just use the shortcode — it keeps the markup consistent and easy to update later.” |
| Discussing performance | ”There’s no hydration step to think about — the whole page is static HTML, so there’s nothing to profile on the client side.” |
Common Mistakes
- Calling the data cascade “just front matter” — front matter is only one layer; directory data files and global data also contribute, and precedence order matters.
- Saying “Eleventy doesn’t support JavaScript” — it supports JavaScript templates and client-side scripts you add deliberately; it simply doesn’t ship a framework runtime by default.
- Referring to a shortcode as a “component” — shortcodes are template-level reusable snippets, not the same concept as a framework component with its own state.
Practice Exercise
- Explain, in two sentences, why the data cascade’s precedence order matters when debugging a page that has the wrong layout.
- Write a short README section explaining what a shortcode does and when to reach for one instead of repeating markup.
- Draft a one-paragraph justification for choosing Eleventy for a documentation site with no interactive features.
Related Resources
- English for Gatsby Developers
- English for Docusaurus Developers
- English for Astro Content Collections
In Practice: Navigating Nuance in Collaboration
Many developers learning English as a second language find themselves grappling with subtle differences in phrasing that can significantly impact communication within a team. It’s not just about knowing the words for “bug” or “refactor,” but understanding how those words are used, and more importantly, when to use them. Consider a scenario: you’ve spent an afternoon meticulously crafting a pull request (PR) detailing changes to a component’s styling. You’re feeling confident, highlighting improvements in responsiveness and accessibility. Then, during code review, your colleague leaves a comment: “This looks… aggressive.”
Now, “aggressive” isn’t inherently negative in English. It can describe something bold or assertive. However, within the context of software development, it’s often used to subtly criticize changes that are perceived as over-styled or disruptive – potentially introducing visual conflicts or breaking existing layouts. The key here is recognizing this nuance. A more constructive response might be, “Could you elaborate on what specifically feels aggressive? Perhaps we can discuss the impact on the overall design system.” This shifts the focus from a subjective judgment to an opportunity for collaborative problem-solving. Similarly, in Slack discussions about performance issues, phrases like “this is slow” are often too vague. Saying, “The API response time is consistently exceeding 200ms under load – could we investigate caching strategies?” demonstrates precise technical language and invites targeted discussion.
Another common situation involves receiving feedback on your documentation or PR descriptions. A reviewer might say, “This needs more context.” This isn’t necessarily a criticism of the content itself, but rather an indication that the explanation lacks sufficient detail for someone unfamiliar with the project to understand the changes being proposed. It’s crucial to remember that clear communication is paramount. Don’t assume everyone shares your level of familiarity – always strive to provide enough background information to ensure understanding. Focusing on actionable language and framing feedback as opportunities for clarification, rather than personal critiques, will drastically improve your collaboration skills.
Finally, mastering the use of conditional phrasing can be incredibly valuable. Instead of stating a definitive problem (“The database is broken!”), you might say, “We’ve observed intermittent issues with database connectivity.” This softer approach acknowledges the situation without immediately assigning blame or escalating urgency. It opens the door for investigation and discussion rather than triggering immediate panic.
eleventy --input data/blog --output .This simple command demonstrates a fundamental workflow within Eleventy – using the data directory as a source of information to generate static HTML pages. The command itself is straightforward, but understanding its purpose—building a website from structured content—is essential for effective communication about the build process and potential issues during deployment.