My Web Development Blog

Eleventy Excellent 4.0

2025-01-11T00:00:00Z

A new version is here! This includes a bunch of breaking changes.
Again I am changing the body font for this update, this time it’s Atkinson Hyperlegible.

New Image handling

I have been clinging to my image shortcode for too long. With the latest major version of Eleventy Image I decided it’s finally time to also include the transform method, because it is awesome.

That alone would not be a breaking change, but I decided to change the existing Nunjucks image shortcode a bit. If you use the shortcode beyond the container class, you must adjust your code to these changes:

( src,
  alt = '',
  caption = '',
  loading = 'lazy',
  containerClass,
  imageClass,
  widths = [650, 960, 1400],
  sizes = 'auto',
  formats = ['avif', 'webp', 'jpeg']
) => { ...

Breaking: widths is now passed in before sizes (because I change this value much more often).
Breaking: imageClass is a new paramteter dedicated to the <img> element, while containerClass is for the container (<figure> or <picture>), as before.
also new: for all images you can start the path relative to the input folder (drop ./src in the path, though it is compatible with ./src being present)

Using the transform comes with the great advantage, that you can now use co-located images with the HTML and Markdown sytnax. 🎉

For a detailed overview of the new image possibilities see the dedicated blog post.

Cascade layers

Inspired by Mayank’s post, I’ve transitioned to using cascade layers, instead of using the :where() pseudo-class to create low-specificity selectors for resets and compositions.

The global CSS bundle is now organized with cascade layers.
The local CSS bundle, used for per-page or component-specific styles, does not utilize cascade layers. As a result, all CSS blocks included have a higher specificity than global styles, regardless of the selector specificity in the global CSS bundle.

Breaking: The “inline” bundle is now called “local”, as this made more sense: all bundles are inlined.

New color system

Run npm run colors after defining your base color values in src/_data/designTokens/colorsBase.json. This will generate or update the colors.json file in the same directory.

Colors under shades_neutral or shades_vibrant are converted into scalable palettes. This is not very elaborate, use a value more or less in the middle of the scale. Happy to receive suggestions for improvements.
Colors listed under standalone and light_dark are left as they are, light_dark items output a second “subdued” version optimized for dark themes.

// this creates a palette with shades of green, 100 to 900
{
  "shades_vibrant": [
    {
      "name": "green",
      "value": "#008000"
    }
  ]
}

src/assets/css/global/base/variables.css changed a lot, as I now use new color names. I also dropped the @supports blocks for color-mix() and the relative color syntax – not because they aren’t great, but I just perceived the whole file as too complex. Now JavaScript does the step of creating subdued colors for the dark theme.

I also considered using the new light-dark() CSS function instead of the repetitive code for prefers-color-scheme and data-theme=“dark”, but the browser support is still too low.

Breaking:: src/assets/css/global/base/variables.css changed. You must adapt your colors in src/_data/designTokens/colorsBase.json if you want to use the npm run colors script.

You can also just completely skip that and define your colors directly in colors.json (I recommend deleting the colors command in package.json in this case, so you don’t unitentionally overwrite your work).

More about colors here.

New button styles

Inspired by Andy’s article, the button styles changed. As the article explains that very well, I won’t say much more about it.

Other new features and changes

border-radius became a design token used by the Tailwind config, to be set in src/_data/designTokens/borderRadius.json.
new 3XS spacing value in src/_data/designTokens/spacing.json.
new grid composition layout data-layout='thirds.
new OG images template. As it uses meta.siteName next to the 11ty Logo, you might have to adjust the template for that src/common/og-images.njk.

Let me know if you have any questions or issues with the update.
I am happy to help you out. Maybe you’ll want to wait a bit, as I will add some more fixes, no doubt.

Post with an image

2025-01-09T00:00:00Z

Using the powerful Eleventy Image plugin, we have three ways to optimize images: HTML Transform, Markdown syntax, and a Nunjucks shortcode.

HTML Transform

Transforms any <img> or <picture> tags in HTML files as a post-processing step. Find the default settings directly in eleventy.config.js.

<img src="./co-located-image.jpg" alt="alt text">
<img src="/assets/images/absolute-path-image.jpg" alt="alt text">

We can pass in overrides for every instance and use attributes. By default all images are set to be lazy loaded, but we can override this by directly setting loading="eager" and decoding="sync"on the <img> element.

Another thing to note is the widths: ['auto'] setting, which by default only includes the original size image. You can set the dedicated widths to be used by adding eleventy:widths="800,1200" on the element. For images with Markdown syntax, I set fixed widths so we don’t need to set a value on every instance.

sizes defaults to auto, which is applied to all lazy loading images. For eager-loading images, the value is equivalent to 100vw See: https://github.com/whatwg/html/pull/8008. We can still overwrite this, by setting the sizes attribute directly on the <img> element, with something specific like sizes="(max-width: 615px) 50vw, 100vw".

<img src="./co-located-image.jpg" alt="alt text" eleventy:widths="200,600" loading="eager" decoding="sync">

This makes this syntax equally powerfull as the shortcode, and easier to read - with the extra benefit that we can use both relative and absolute image sources.
Only “downside” ist, that it comes with a higher build cost due to the post-processing step.

More info: https://www.11ty.dev/docs/plugins/image/#html-transform

Markdown syntax

This also uses Image HTML Transform .
The markdown sytnax for images creates the <img> element the plugin is looking for, and then transforms it to the <picture> element (if more than one format is set).

In src/_config/plugins/markdown.js I customized the Markdown rendering for images slightly. What normally would become a title attribute is used to create a caption. Note that I set a fixed widths value instead of auto as the default.

![alt text](/path/to/image 'caption text')
![Close-up with unfocused background of a vibrant large blue butterfly gracefully perched on a delicate flower amidst lush green gras](/assets/images/gallery/asturias-4.jpg) 'I used a portrait lens for this one'

I used a portrait lens for this one

You can also add custom attributes here (Kudos to Aleksandr), to overwrite the default widths, have the image eagerly loaded, or add a class etc.

![alt text](/path/to/image){attrs}
![Close-up of a delicate white flower with a yellow center, surrounded by green leaves](/assets/images/gallery/asturias-2.jpg){loading="eager" decoding="sync" eleventy:widths="400" class="grayscale"}

Nunjucks shortcode

The most basic version contains the path to the image (absolute) and alt text (can be an empty string if the image is decorative).

{% image "path to image", "alt text" %}

It defaults to loading = 'lazy', the picture element gets its set of images from widths=[650,960,1400] and compares to a condition of sizes="auto".
You can pass in manually all the conditions, add null to skip. The arguments include classes for the outer container ( <picture> or <figure> element), and for the <img> element.

The shortcode is stored in src/_config/shortcodes/image.js.

{% image "path to image", "alt text", "caption text", "eager", "container class names", "img class names", [200, 400], "(min-width:30em) 50vw, 100vw" %}
{% image "path to image", "alt text", null, "eager" %}

What a nice old house in black and white

Example: predefine widths and sizes using Nunjuck’s set tag or front matter fields, and dynamically get the image path, like I do in the built-with template.

{% image "/assets/images/screenshots/" + site.filename + ".jpg", site.name, null, "lazy", null, null, widths, sizes %}

Comparing Shortcode and HTML Transform

The shortcode can be much terser than the HTML syntax. It also includes the slot="image" attribute for seamless WebC component integration. However, it’s less readable, and you must carefully order all arguments. On the other hand, the HTML syntax is much more readable and easier to maintain.

As for the higher build cost of post-processing, the shortcode images are being skipped using the eleventy:ignore attribute, but still seem to be processed somehow. I have yet to figure out if this is avoidable. If you set the eleventy:ignore on an HTML image though, it is completely skipped and excluded from the processed images.

These two approaches produce (almost) the same output:

{% image image, alt or title, credit, "eager", "feature", "grayscale" %}

<figure class="feature">
  <img src="{{ image }}" alt="{{ alt or title }}" loading="eager" decoding="sync" class="grayscale">
  {% if credit %}
  <figcaption>{{ credit }}</figcaption>
  {% endif %}
</figure>

A photo I took.

Eleventy Excellent 3.0

2024-06-03T00:00:00Z

It’s been a few months, and I have decided to change things again, which probably makes the starter even more opinionated 🤷. For those who prefer the previous version, Version 2 will remain accessible in its own branch.

Core changes:

ESM! I originally wanted to wait for the beta version of Eleventy 3.0, but the alpha version works absolutely fine, so I decided to go for it.
a new font for the body (base) text: Inclusive Sans. Only has Regular 400 and Regular 400 italic for now, so bold uses the display font.
A new config structure (turns out I am the Eleventy config person!). I also decided to have everything inside the src folder. More about that in the docs.
some new filters, for having markdown format in the frontmatter, and for sorting.
there is now a “setup” directory inside of the _config folder, for automatic favicon creation and to add the screenshots to the “built with” section. They are triggered by new scripts in package.json. See also “Favicons” in the docs.
SVGs are now in src/assets/svg, and there is a new SVG shortcode to include them. I also explain this in the SVG section.
I now actively use Eleventy’s plugins WebC (for components), the bundle plugin and<is-land>.
I made small CSS changes everywhere - and introduce a new structure, also explained in the docs.
JavaScript handling changed a lot, too.
Also: improvements in terms of organization and naming.

I don’t consider myself a JavaScript person, and I still struggle to fully grasp WebC. So, if you have any suggestions or improvements, in particular to the WebC and web components code, please don’t hesitate to reach out or send a PR.

Plans for the future:
This starter was meant to be hosted on Netlify, and I’d like to change that so that it works with any host without much extra effort.

I hope you enjoy the new version! 🌟
And, should you decide to upgrade – sorry for not making this easier for you. I hope that you don’t face too many difficulties!

Eleventy Excellent 2.0

2024-02-01T00:00:00Z

I changed so much, that documenting everything will be hard. I will try and name the most important changes in the next few weeks.

Maybe a quick “why” first

I created this starter after I saw Andy’s talk and studied the source code for buildexcellentwebsit.es.

I quickly came to the conclusion that this is the way I want to build all my websites from now on! It’s so great. I know many of you feel the same way.

I had already accumulated a lot of opinions, files and basic settings from my previous Eleventy projects, and to make it easier for me to start a new project in the future, I combined everything in this starter. The name is a tribute to its origin:

“Go Forth And Build Excellent Websites”!

When that was finished, I thought it was only fair to make it easily accessible to others, and at the end of 2022 I registered the starter with the official stater projects.

What I didn’t count on, was how many people would actually go and use the starter.

So many of you have also contacted me or contributed something.

I wanted to make the starter better

I have since made sure that everything stays fairly updated, fixed a few bugs and added a few features – but I haven’t quite dared to change the base too much, now that so many others were involved.

The thing is, I have learned lots of new things and changed my mind about other stuff like naming or organization in the last year and a half. Whenever I begin a project now, I still turn to this starter – but I modify a lot before I get started. This goes above all for the organization and naming of files and folders, modern CSS, and better accessibility.

You will see that many things are new and different, but better! And that the basic character is still the same.

I will try and take some time to document important changes so you can upgrade more easily.

I have kept v1 in a separate branch.

Plans for the future

I will change everything to ES modules as soon as Eleventy v3 with ESM support is stable.
I might bring back the drawer menu as something to opt in (Update: I did this already, see “Get started”).
Lots of small fixes, no doubt.

Thank you and let’s build more excellent websites!

Post with a gallery

2024-01-30T00:00:00Z

This post has a gallery set in its front matter as a list of objects, each with an image, alt, and caption property.

When you import the gallery component, the images are listed in a grid as buttons, each linked to the respective image in a <dialog> HTML element. A close button within each dialog allows the image to be hidden again. Includes gallery.css for styling the modal dialogs and backdrop, gallery.js manages modal dialog interactions.

Loop through images without additional interactivity:

What is Tailwind CSS doing here?

2023-11-30T00:00:00Z

Update February 2024:
The CSS system of this starter was invented by Andy Bell.
I wrote the following explanation quite quickly after hearing several times that people are confused about normal Tailwind CSS classes not working. In the meantime, Andy has published a better and more detailed explanation.

We are using Tailwinds “engine” to generate utility classes on demand, based on our design tokens.

If you have a look at the tailwind.config.js, you can see how that is done. For example, we are deactivating Tailwinds default reset.

We are hooking into the components layer, to make Tailwind output classes based on our tokens, instead of their default design system.

That is, you are able to use mt-xs-s instead of a class like mt-20 for example. Same goes for colors, depending on the namesin your colors.json, you get custom classes like text-pink. These use the usual Tailwind prefixes (see docs to learn how to generate colors).

You get a custom property mapped to the color name --color-my-custom-color-name and the classes bg-my-custom-color-name as well as text-my-custom-color-name.

Consider that we limit those utilities in the theme section:

backgroundColor: ({theme}) => theme('colors'),
textColor: ({theme}) => theme('colors'),
margin: ({theme}) => ({ auto: 'auto', ...theme('spacing')}),
padding: ({theme}) => theme('spacing')

If you want to add the generation for border-color classes for example, you’d have to add that right there:

borderColor: ({theme}) => theme('colors')

Also. you do have something like md:text-right available because we define the screens (src/_data/designTokens/viewports.json):

screens: {
  ltsm: {max: `${viewportTokens.sm}px`},
  sm: `${viewportTokens.sm}px`,
  md: `${viewportTokens.md}px`,
  navigation: `${viewportTokens.navigation}px`
},

Additionally, you get custom properties based on the naming of your design token files:

const groups = [
  {key: 'colors', prefix: 'color'},
  {key: 'borderRadius', prefix: 'border-radius'},
  {key: 'spacing', prefix: 'space'},
  {key: 'fontSize', prefix: 'size'},
  {key: 'lineHeight', prefix: 'leading'},
  {key: 'fontFamily', prefix: 'font'},
  {key: 'fontWeight', prefix: 'font'}
];

In your dev tools you can see all the generated custom properties + your custom ones from css/global/variables.css.
They are generated by default.

You can also create custom utility classes:

const customUtilities = [
  {key: 'spacing', prefix: 'flow-space', property: '--flow-space'},
  {key: 'spacing', prefix: 'region-space', property: '--region-space'},
  {key: 'spacing', prefix: 'gutter', property: '--gutter'}
];

If you install the Tailwind CSS IntelliSense addon, you can actually see the classes available to you, including the color preview.

Read some thoughts that lead Andy Bell to come up with that approach: https://andy-bell.co.uk/i-used-tailwind-for-the-u-in-cube-css-and-i-liked-it/

Demo pages

2023-10-30T00:00:00Z

Important: As of version 2.0, the demos featured here are all directly built in the starter.

I did not want to clutter the starter with too many features, that you might not need, but I find myself using them frequently for my own projects, so now they are “baked in”.
I will keep the old demo repos for the moment, but they are not maintained and are deprecated.

If you never saw version 1, nevermind.

Demos

Gallery

A gallery with good old "popup" functionality inside a dialog element and a regular loop over images.

Demo

Pagination

The blog collection with a pagination. To work with visual current page indication, :has() pseudo-class support is required.

Demo

Open Graph images

2023-01-25T00:00:00Z

When you share your blog posts, a thumbnail image may appear - the image we define in our meta data as an Open Graph Image (og:image).

This starter generates these images for your blog posts automatically. They take in the title and date of the post.

This is what an OG image for a blog posts looks like

The fallback and default image for all other pages is the image set as opengraph_default in the meta.js global data file.

This is what the general OG image for non-blog posts looks like

A more detailed explanation can be found in the docs.

Post with all the markdown

2022-11-02T00:00:00Z

A lot of markdown packages are installed to help you write your posts.
You can configure them in config/plugins/markdown.js.

As of my personal preference, there are some presets. For example the conversion of web pages to links (www.lenesaile.com) and the addition of rel="noopener" for external links (all links with the pattern /^https?:/).

This is a tiny pitfall!
Take care to not prefix your internal links with your domain, or else they will be treated as external. To link internally, use this pattern:

An internal link to the [about page](/about/)

h2 Heading

h3 Heading

h4 Heading

Muffin bonbon jujubes cheesecake chupa chups shortbread ice cream cotton candy cake. Jelly-o biscuit dessert danish dessert pastry tootsie roll lemon drops gingerbread. Cheesecake donut marzipan sweet roll icing muffin halvah. Dragée donut cake biscuit pie carrot cake sesame snaps jelly-o gummi bears.

Soufflé topping shortbread lemon.

hr

Typographic replacements

The replacement converts this input:

(c) (C) (r) (R) (tm) (TM) +-
and so on.. and so on... and so on..... AND SO ON???????.....
WTF!!!!!! How many exclamation marks are you going to use????????????
,, -- ---
"double quotes" and 'single quotes'

To this:

© © ® ® ™ ™ ±
and so on… and so on… and so on… AND SO ON???..
WTF!!! How many exclamation marks are you going to use???
, – —
“double quotes” and ‘single quotes’

Emphasis

This is bold text
This is italic text
~~Strikethrough~~

Blockquote

Cheesecake donut marzipan sweet roll icing muffin halvah. Dragée donut cake biscuit pie carrot cake sesame snaps jelly-o gummi bears. Cotton candy cookie croissant fruitcake.

Lists

Unordered lists

Create a list by starting a line with +, -, or *
Another item

Ordered lists

Lorem ipsum dolor sit amet
Consectetur adipiscing elit
Integer molestie lorem at massa

Code

Syntax highlighting

.back-top-top {
  padding: 10px;
  background: white;
  margin-top: 110vh;
  position: sticky;
  bottom: 0;
}

/* by David Darnes */

Tables

Technology	Fun fact
HTML	HTML (Hypertext Markup Language) was created by Sir Tim Berners-Lee in 1991 as a way to structure and link documents on the World Wide Web.
CSS	It’s called “cascading” because styles can cascade down from parent elements to their children, allowing for inheritance and overriding.
JavaScript	TypeError: null is not an object

Links

Read all those articles
Autoconverted link https://every-layout.dev/ (enabled via linkify)

Emojis

Literal:
🤩 💯 💚 👻 👾

Classic markup:
😢 💩 🔥 😆 🎄
(A reference for emoji markup)

Shortcuts (emoticons):
😃 😦 😎 😉 😛

mark

Marked text

Footnotes

Footnote 1 link^[1].
Footnote 2 link^[2].

*[HTML]: Hyper Text Markup Language

Images

Consider that src is already prepended in the settings.

Footnote can have markup
and multiple paragraphs. ↩︎
Footnote text. ↩︎

Post with a video

2022-10-31T00:00:00Z

This starter uses a webC version of Paul Irish’s lite-youtube-embed.

Alberto Ballesteros - Artista Sin Obra

A modified version to display PeerTube videos is also included (Thank you camperotactico). It works similarly, but takes two extra arguments:

@instance: The instance hosting the video.
@embed-slug The slug used for video embedding.

Back at the Herperduin 💦 - 28/09/2024

Learn more in the video docs.

Post with some code

2022-09-01T00:00:00Z

This theme uses 11ty’s Syntax Highlighting Plugin, a pack of Eleventy plugins for PrismJS syntax highlighting. No browser/client JavaScript, highlight transformations are all done at build-time.

const cards = [...document.querySelectorAll('.card')];
cards.forEach(card => {
  card.style.cursor = 'pointer';
  let down,
    up,
    link = card.querySelector('a');
  card.onmousedown = () => (down = +new Date());
  card.onmouseup = () => {
    up = +new Date();
    if (up - down < 200) {
      link.click();
    }
  };
});

// © Heydon Pickering

.smol-container {
  width: min(100% - 3rem, var(--container-max, 60ch));
  margin-inline: auto;
}

/* © Stephanie Eckles, https://smolcss.dev/ */

Edit styles in css/blocks/code.css

Post with 301 redirects

2022-08-28T00:00:00Z

URLs usually change over time, as you use another CMS or optimize your file structure.

A 301 is used when a page has permanently changed location.
Informing about this change is indispensable if you want to keep your incoming links working, be it from organic Google search or other pages that have linked to your content.

Aleksandr Hovhannisyan came up with an elegant solution for Eleventy and Netlify. To directly cover several possible previous routes it is created as an array. You can find the loop in _redirects.njk.

Usage

Frontmatter:
---
redirectFrom: ['/old-route/', '/optionally-another-old-route/']
---

Post with fetched content