Huwindty 🌬️

Search

2026-10-15T21:24:41Z

Pagefind

Pagefind is a search tool that can run on static sites like eleventy. It claims to perform well on large sites, but its main interest is to not rely on any external service or infrastructure and use very small bandwidth. This makes it a good choice for smaller sites too.

This choice was guided from a post from Mike Fallows going for this option after having checked solutions like Algolia (relying on an external service) and adding Lunr to an Eleventy site which is simpler, works well, but uses much more bandwidth.

How Pagefind was added to huwindty

HTML only search form

The first thing was to build a fallback search form for users without javascript. This is not a bad idea to think about such users on a static site. This search form, following an example from Zack Leatherman on his pagefind-search web component is sending requests to DuckDuckGo with instruction to only show results from a certain domain (your site’s domain).

In this case search requests are sent to DuckDuckGo but you can use any other search engine of your choice.

<div class="transition fixed -right-5 top-0 p-2 translate-y-0 mr-5" id="duckduckgo" > 
  <!-- default form is the fallback when nojs -->
	<form action="https://duckduckgo.com/" method="post" class="group/search min-h-2.5"><!-- min-height to reduce CLS -->
		<label>
			<span class="md:invisible group-focus-within/search:invisible align-bottom cursor-pointer fixed top-6 right-18"><span class="sr-only">Search :</span> 🔎 </span>
			<input placeholder="Search this site" type="search" id="searchinput" name="q" autocomplete="off" class="
      w-0 md:w-35 p-0! md:p-2! -mr-6 border-0 border-black md:border bg-white rounded-xl
      fixed top-2 right-10
      delay-100 duration-300 ease-in-out 
      group-focus-within/search:p-2! group-focus-within/search:max-w-[calc(80vw-50px)] group-focus-within/search:w-150 group-focus-within/search:mt-18" onfocus="loadPagefindUI()"
      />
		</label>
		<input type="hidden" name="sites" value="{{meta.url}}" />
	</form>
</div>

In that form, the input that helps the search engine only for your site is the hidden “sites” input. The value of your public site’s URL is coming from the meta.json data file so that the search result page will only show links to that domain. Make sure this url is the right one.

You’ll also note the label and submit button with "sr-only" class that make them available on screen readers only when on the screen users will see the magnifying glass.

Pagefind block

After that, Pagefind documentation suggests to load the pagefind css and javascript files and then to perform some changes after all the page content is loaded.

<link href="/pagefind/pagefind-ui.css" rel="stylesheet">
<script src="/pagefind/pagefind-ui.js"></script>

<div id="search"></div>
<script>
    window.addEventListener('DOMContentLoaded', (event) => {
        new PagefindUI({ element: "#search", showSubResults: true });
    });
</script>

To maintain the high performence of page load, I decided on another approach. Css will be added inline just before the html block for search.

<style>
  .pagefind-ui__message {
    font-weight: bold;
  }
  .pagefind-ui__results {
    list-style-type: none;
  }
  .pagefind-ui__result-title {
    margin: 20px 0 10px;
  }
  .pagefind-ui__result-excerpt {
    margin: 5px 0 20px;
  }
</style>

<div id="searchdiv" class="search"></div>

Then, the javascript file is loaded only when it is likely to be used, when the user focusses on the search input (by click of by tabulation). This is done with the onfocus="loadPagefindUI() that you can see above.

  const loadPagefindUI = () => {
    if (typeof PagefindUI === "undefined") {
      var script = document.createElement('script');
      script.setAttribute('type', 'text/javascript');
      script.setAttribute('src', "{{ meta.url }}/pagefind/pagefind-ui.js");
      script.addEventListener('load', function() {
        initPagefindUI()
      });
      document.body.appendChild(script);
    }
  }

When loading the script, you notice an event listener that is loaded once the script is loaded. initPagefindUI() is the function that hides the fallback input and copies over its styles to the new pagefind input.

The src attribute is an absolute URL with {{ meta.url }}. If the Huwindty site is right after the domain, /pagefind/pagefind-ui.js is sufficient.

    document.getElementById('duckduckgo').classList = 'hidden';

    const searchInput = document.getElementById('searchinput');
    searchInput.removeAttribute('id');
    const pageFindForm = document.getElementsByClassName('pagefind-ui__form')[0];
    pageFindForm.classList.add('group/search');
    const pageFindInput = document.getElementsByClassName('pagefind-ui__search-input')[0];
    pageFindInput.classList = searchInput.classList;
    pageFindInput.setAttribute('id', 'searchinput');
    pageFindInput.setAttribute('aria-label', 'search');
    pageFindInput.focus();
    document.getElementsByClassName('pagefind-ui__search-clear ')[0].classList = 'hidden';

Pagefind input doesn’t come with a label, so it is added with javascript:

  const label = document.createElement('LABEL');
  const labelText = document.createTextNode(' 🔎 ');
  label.appendChild(labelText);
  label.classList.add('md:invisible', 'group-focus-within/search:invisible', 'p-4', 'align-bottom', 'cursor-pointer', 'absolute', 'top-2', 'right-15');
  label.setAttribute('for', 'searchinput');
  pageFindInput.insertAdjacentElement('beforebegin', label);

It also performes a few other style modifications depending on the context. For exemple, the main content of the page is hidden to leave space to search results.

    // hide page content if there is a search term
    pageFindInput.onkeyup = () => {
      const hamburger = document.getElementById('hamburger');
      const header = document.getElementsByTagName('header')[0];
      const article = document.getElementsByTagName('article')[0];
      const sections = [...document.getElementsByTagName('section')];
      if (pageFindInput.value.length > 0) {
        hamburger.checked = false;
        header.classList.add('hidden');
        article.classList.add('hidden');
        sections.forEach((sections) => { sections.classList.add('hidden'); });
      } else {
        header.classList.remove('hidden');
        article.classList.remove('hidden');
        sections.forEach((sections) => { sections.classList.remove('hidden'); });
      }
    }

Pagefind index generation

The next step is to make sure that pagefind generates its index, right after eleventy generated the static pages. This is done by adding the pagefind command at the end of the eleventy.js config file.

const { execSync } = require('child_process')
// (…)

  // pagefind search
  eleventyConfig.on('eleventy.after', () => {
    execSync(`npx pagefind --source _site --glob \"**/*.html\"`, { encoding: 'utf-8' })
  })

You may want to restrict the indexed pages by slightly editing the \"**/*.html\" glob.

Select useful content

For each page, you typically want to avoid indexing header, menu and footer. In fact

It is also necessary to tell pagefind where is the useful content of the pages by adding the attribute data-pagefind-body in the layout for the sections that contain content. Typically, we avoid to index the content of headers, footers and menus.

<article data-pagefind-body>

On Huwindty, the attribute data-pagefind-body was added to the article part of the home page, index page and the default layout. It doesn’t include the header with its title and headline, but you can add it yourself if this makes sense to you.

How pagefind search works

Once you’ve done all this and you generate the eleventy site, it will also generate the pagefind folder that contains all search scripts and indexed data.

All pages also contain the <div id="searchdiv" class="search"></div> block that was added in the layout. This block contains the search field and will also contain the list of search results, right under the search input, when users perform a search.

When search result display, it shows in the current page and the page content hides to avoid confusion. All this is presented thanks to the additional styling explained bellow.

Pagefind styling

The search form style is handled with the init script.

For the result page, since we don’t use the default pagefind styles, the default styles apply. We made sure that the term highlighting and the button were defined in the default (tailwind.css) theme.

  & mark {
    @apply bg-amber-200;
  }
  & button {
    @apply bg-blue-500 hover:bg-blue-800 text-white font-bold py-2 px-4 rounded-2xl;
  }

Accessibility

Both fallback and pagefind search should be fully accessible. To make it more accessible, search should be accessible early on the tabindex.

Because there may be a long menu before the search form, a shortcut link labeled “Search this site” has been added on the very top of the page.

  <a href="#searchinput" id="searchthissite" class="fixed transition left-4 top-12 bg-secondary text-bg p-3 m-5 -translate-x-72 focus:translate-x-12 z-2">Search this site</a>

Keyboard shortcut

I had a discussion with Bob Monsour from 11tybundle about adding a shortcut to perform this search. While this sounds practical, this may interfere with some of the browser shortcut. If you want to implement this shortcut, Bob explains how he did.

Navigation

2026-10-15T21:24:41Z

Navigation principles

11ty Navigation Plugin

The 11ty Navigation Plugin is a plugin that allows to define and display a navigation menu form pages. It relies on a series of codes added to the Front Matter of pages, giving eanch page at least a key.

eleventyNavigation:
  key: Bats
  parent: Mammals
  title: The bats
  order: 2

Huwindty doesn’t use this plugin.

Collections

In Eleventy, collections allow you to group pages according to tags added in the front matter. By naming different tags, you can group content in an interesting manner. There is also a collections.all that lists all pages, even those without tags.

collections.all lists all pages in a folder that is identified by an index file with front matter. Empty folders or folders without an index.md or with an empty index.md will not be taken into account.

If you want to exclude a page from the navigation (typically the 404 page and similar), you can exclude it from collections.all by adding the following line in the page’s front matter:

eleventyExcludeFromCollections: true

Huwindty navigation menu is build automatically from collections.all.

Navigation Menu Structure

The navigation utilizes collections.all to list all pages. It displays all first-level pages in the main menu, with nested pages organized under their respective submenus. The menu hierarchy mirrors the exact file structure of the collection’s pages.

Collections are sorted by file date. The hierarchy of the navigation follows this order, older first and most recent at the bottom. If you want to change the order of the navigation, just add a date: within the front matter of each page.

You can also reverse the order of the navigation items by adding a filter to the collection value setting {% set allEntries = collections.all | reverse %}. Doing it in the menu.njk will revert the order in the horizontal menu and doing it in renderNavItem.njk will revert the order in the vertical submenus.

Index Pages

Sections appear in the menu as clickable links. Since some of these pages might lack content, you can automatically list the pages within a section by using the index layout. Additionally, you can include a title for this list using the toc key in the front matter.

layout: index
title: Documentation
toc: Table of content

How does it work?

The navigation menu can be added to the nunjucks template of your choice by just including menu.njk.

{% include "menu.njk" %}

First loop on collections

menu.njk will loop on collections.all and parse the URL of each entry.

The first-level entries are the ones with 3 chunks (more if you have a long path). From this point we will use the nunjucks macro renderNavItem(entry) to display the entry in the menu.

If the entry contains nested pages, the macro will handle it by loading itself again (see below).

  {% set allEntries = collections.all %}
  <ul role="list" class="flex">
    {%- for entry in allEntries %}
      {% if entry.url.split("/").length === 3 %}
        {{ renderNavItem(entry) }}
      {% endif %}
    {% endfor %}
  </ul>

The link to the home page, which has fewer chunks of URL, is hard-coded at the beginning of the navigation. This allows you to shape the link to home the way you want, with the word “home”, another word, or even directly by adding your website’s logo.

    <li class="relative group">
    <a href="/" {% if entry.url == "/" %} aria-current="page" {% endif %}
      class="block p-4 text-nowrap hover:text-blue-300"
      >ॐ sweet home</a> 
    </li>

Next loop on collections for nested pages

For each entry, renderNavItem(entry) will first look if the entry contains nested pages. If it does, it will set them as children.

  {% for menuEntry in Allentries %}
    {% if menuEntry.url.split("/").length === level + 1 %}
      {%  if menuEntry.url.split("/")[level-2] === entry.url.split("/")[level-2] %}
        {% set children = (children.push(menuEntry), children) %}
      {% endif %}
    {% endif %}
  {% endfor %}

If the entry has children it will contain a sub list where all entries will be handled, including their possible subsets, by calling the macro again.

  {% if children.length %}
    <li>
      <div>
        <a href="{{ entry.url }}">{{ entry.data.title }}</a>
        <ul role="list">
          {%- for child in children %}{{ renderNavItem(child) }}{% endfor -%}
        </ul>
      </div>
    </li>

Entries without children will be displayed normally.

  {% else %}
    <li class="relative group">
      <a href="{{ entry.url }}">{{ entry.data.title }}</a> 
    </li>
  {% endif %}

Styling the navigation menu items as needed

Since the navigation menu is a list with possible sublists, it is rendered on the page the way lists are styled. The styled are applied using tailwind according to their level. They are added to the list loop using smaller macros aClass and ulClass.

First level entries are styled with a different colour

  {% if entry.url.split("/").length === 3 %}
    block p-4 text-nowrap hover:text-blue-300
  {% endif %}

and their sub-blocks display on hover

{% macro ulClass(entry) %}
  {% if entry.url.split("/").length === 3 %}
    absolute left-0 hidden bg-bg text-text shadow-lg group-hover:block
  {% endif %}
{% endmacro %}

Second level entries are displayed under their parent entry, in a drop-down menu.

  {% if entry.url.split("/").length === 4 %}
    block p-4 text-nowrap hover:underline
  {% endif %}

We also add a negative margin in case this section has children. These children will show closer to their parent so that the user can identify clearly each section.

  block p-4 text-nowrap hover:underline {% if children.length %}-mb-4{% endif %}

The following entries will display in the same drop-down block with only smaller font and additional padding.

  {% if entry.url.split("/").length >= 5 %}
    block px-4 py-0 text-sm text-nowrap hover:underline
  {% endif %}

Responsiveness

On smaller screens the menu is hidden behind a hamburger icon that will toggle on and off the navigation menu without using javascript.

    <input id="hamburger" type="checkbox" name="hamburger" class="md:hidden sr-only peer" unchecked />
    <label for="hamburger" class="after:content-['≡'] peer-checked:after:content-['✕'] md:hidden cursor-pointer">
      <span class="sr-only">Menu</span>
    </label>

The hamburger is not displayed on larger screens thanks to md:hidden but it will be focusable and “visible” to screen readers thanks to sr-only.

What displays on the screen is the after content that depends on if the checkbox is checked (peer-checked:after:content-['✕']) or not (after:content-['≡']).

  <ul role="list" class="mt-12 md:mt-0 md:flex hidden peer-checked:block">

Accessibility

Because the label of the hamburger is not visible on screen, it is necessary to add aria-label="menu" to the checkbox input.

Additionaly, there is an aria attribute on the menu entry of the current page.

{% if entry.url == page.url %} aria-current="page"{% endif %}

Finally we want each menu entry to be focussable even when it doesn’t display on the screen. For this we need to do two things: first display the submenus also when the entry menu is focussed, and second to make sure the submenu remains on display when any item is focused. This is the same logic as the :hover pseudo class but with :focus.

To style an element depending on the pseudo class of the parent, tailwindcss allows the use of the class group that allows many conditions. For example, the following css code:

  li:hover ul { display: block; }

can be generated with the following tailwindcss classes:

<li class="group">
  <a href="/link">Link</a>
  <ul class="hidden group-hover:block">
    <li>
      <a href="sublink">sublink</a>
    </li>
  </ul>
</li>

The same group class is used for the focus. However, because focus only applies to an anchor without considering the parent elements, we need to use the pseudo-class :focus-within.

<li class="group">
  <a href="/link">Link</a>
  <ul class="hidden group-hover:block group-focus-within:block">
    <li>
      <a href="sublink">sublink</a>
    </li>
  </ul>
</li>

Thanks to this we have a nice menu that can be browsed naturaly using tabindex. No entry can be mised even when using a touchscreen or a screen reader.

The index pages

The list of sub pages on index.md and index.html pages is displayed thanks to the index.njk layout. It lists all pages with title and headline. It uses the default style for markdown pages but can be customised the way you want.

  {% for post in collections.all %}
    {% if post.url.startsWith(page.url) %}
      {% if post.url !== page.url %}
        {% if post.url.split("/").length === page.url.split("/").length + 1 %}
        <p>
          <a href="{{ post.url }}">{{ post.data.title }}</a><br>
          <em>{{post.data.headline}}</em>
        </p>
        {% endif %}
      {% endif %}
    {% endif %}
  {% endfor %}

Collections and tags

Huwindty doesn’t come with examples of index that spreads on several pages. This is possible thanks to eleventy build in pagination.

Tags are not collections and need a little work before they can be paginated. An example of paginated indexes with categories and tags have been implemented using Huwindty and is documented here.

What next?

You may want to update the styles directly in both menu.njk and renderNavItem.njk as well as index.njk so that they fit your needs.

If you do not need such a menu in your website, just remove these files and carry on.

Styles

2025-10-15T00:00:00Z

Tailwind CSS

Tailwind CSS is a CSS framework that allows you to write more concise and maintainable CSS code thanks to utility classes . Tailwind focuses on providing low-level utility classes that can be combined directly in the markup of any component.

Tailwind CSS generates CSS code using a combination of configuration files, JavaScript, and PostCSS plugins. This generated file only contains the utility classes that are used in the project, thus reducing the size of the final CSS file compared to other CSS frameworks.

CSS generation

In the origin starter windty, css was generated with a separate run script in packages.json. The default npm start was triggering both 11ty and tailwind generation. The Postcss configuration was in a separate file.

For huwindty, the CSS generation is managed by directly in eleventy.js. It is gererated as any other template styles.css.njk that includes the css from the main tailwind configuration file: _assets/css/tailwind.css.

---
eleventyExcludeFromCollections: true
permalink: /css/styles.css
---

{% set css %}
  {% include "../../_assets/css/tailwind.css" %}
{% endset %}
{{css | postcss | safe}}

Thanks to the permalink: /css/styles.css, the static site css file is generated in root of the _site folder.

The file tailwind.css is the css file that imoports tailwind, it loads it anc contains extra definiions that can but then used in your project. For examplpe it contains a @theme defining the color scheme and @utility mkdn that sets the default style of the page content.

@import 'tailwindcss';

@theme {
  --color-primary: #155dfc; /* blue-600 */
  --color-secondary: #372aac; /* indigo-800 */
  (…)
}

@utility mkdn {
    & h2 {
    @apply mt-8 mb-6 text-left text-2xl font-bold leading-tight text-secondary dark:text-secondary-dark;
  }
  (…)
}

The style is processed with tailwind as part of the site generation with a postCSS filter that it added to the layouts in eleventy’s config.

  // Watch targets
  eleventyConfig.addWatchTarget('src/_layouts/css/tailwind.css');
  
  // process css
  eleventyConfig.addNunjucksAsyncFilter('postcss', postcssFilter);

The filter is defined in eleventy.js as a callback that sets the postCSS configuration. After processing the tailwind rendering, it minifies the css with cssnano.

const postcssFilter = (cssCode, done) => {
  postCss([
    tailwind(), // process tailwind with postcss
    autoprefixer,
    cssnano({ preset: 'default' }) // minify css
  ])
    .process(cssCode, {
      from: './src/_layouts/css/tailwind.css'
    })
    .then(
      (r) => done(null, r.css),
      (e) => done(e, null)
    );
}

This configuration was inspired by the blog post How to Integrate PostCSS and Tailwind CSS.

Tailwind and Markdown

Tailwind CSS is ideal to use in html files, but markdown doesn’t support tailwind utilities. For this, there are two solutions: Create custom Tailwind components and add classes to the Markdown output. Both are explained in detail in the blogpost Eleventy, Markdown, and Tailwind CSS

In order to keep markdown files to focus on content I chose to implement the first one (Create custom Tailwind components) in this starter. These are the rules listed in tailwind.css under @utility mkdn.

These default styles can also be rendered within an html file by adding a class mkdn to an html wrapper element. This is the case for example in the index.njk layout.

Additional markdown styles

In addition, the markdown-it-attrs plugins allows for additional classes to be added to the markdown output. This allows to add specific styles to markdown components.

To apply specific styles, the markdown-it-attrs plugin is simply added to the call for the markdown parser markdown-it that is loaded in eleventy.js. (See Markdown)

This is capability can get styles look messy very quickly. It is recommanded to only use it for a few classes.

As an example the note above is generated with the following markdown text:

This is capability can get css messy very quickly. It is recommanded to only use it for a few classes.{.note}

and is styled thanks to the following css class that is also added under @utility mkdn:

  .mkdn .note {
    @apply text-cyan-900 bg-sky-200 border p-4 border-cyan-900 border-l-8
    before:content-['ⓘ_Note:_'] before:font-bold
  }

This is also possible to use tailwind utility classes in markdown. It can be used to add extra style but will not override the defaults defined with @utility mkdn. These default will always take precedence.

In this text all utility classes are used except the text colour.

For example, the frame above is styled with the following:

{.p-8 .bg-orange-800 .text-sky-300 .border .border-4 .border-sky-300}

but you can see that the text is not in the expected colour because the @utility mkdn defines the colour of the text in every paragraphs and this takes precedence.

In this text all utility classes are used even the text colour.

You can make the text colour overide the base utility with the ! symbol that acts in tailwind as the usual !important css. The example above is styled with the following:

{.p-8 .bg-orange-800 .text-sky-300! .border .border-4 .border-sky-300}

Even if you have the capability to use as many styles as you want, use all tailwind utility classes and even ! to orveride base utilities, it is recomanded to keep it simple and use it scarely. Markdown is great to help you focus on your content. You should not ruin it with distracting pieces of code.

Dark theme

Users can set their system and browser to favour a dark or light theme. In this case you should deliver pages that correspond to this wish. In CSS, this can be defined with the media feature @media (prefers-color-scheme: dark). But you on’t be using it since tailwind will do it for you.

theme colours

Themes are defined in tailwind.css under @theme. It consists of a collection of preset colours that are used throughout the layouts and templates. Some of these colour variables have a suffix -dark that defines the colour for the dark theme.

@theme {
  --color-primary: #155dfc; /* blue-600 */
  --color-secondary: #372aac; /* indigo-800 */
(…)

  --color-primary-dark: #4657CE; /* blue-400 */
  --color-secondary-dark: #7591f3; /* blue-300 */
(…)
}

Using theme colours

Tailwind allows to use these colour variables as a normal tailwind utility class, replacing the colour with the name of the element you want to style. For example bg-primary will be the same as --bg-blue-600.

Every component that should change colour between light and dark theme will use both variables in two different classes. The light colour will be the default and the dark colour will be prefixed by dark:.

For example the medu of the current site changes background colour from blue to dark indigo. bg-primary and dark:bg-bg-menu-dark but the text remain white as text-bg is the only text colour class; there is no dark:text-***.

<nav class="w-full bg-primary text-bg dark:bg-bg-menu-dark text-xl md:flex-shrink-0" id="navigation">

Tailwind documentation has more details on dark mode.

Manual theme switcher

Most of the time the light or dark theme can be set in your browser under Web site appearence and the site that handles it can deliver the right theme for it. Some web sites offer users to manually switch from one theme to another (often with a terrible UX).

If you want to use such toggler, You can follow the instructions in Toggling dark mode manually from the Tailwind documentation ans add a custom variant in the main tailwind.css.

@custom-variant dark (&:where(.dark, .dark *));

The toggler that comes with Huwindty follows these instructions, it will add a class dark or light on the main document element <html> and all tailwind classes under dark: will be generated with the .dark prefix.

This switch has three positions: light, browser default and dark.

The widget is placed in the footer footer.njk and used hidden radio buttons. The script src/_assets/js/themeswitch.js handles the theme changes by doing two things:

Add or remove the dark or light class to the main document element <html>.

document.documentElement.classList.add(theme)

Save the theme choice in the browser local storage

localStorage.theme = theme;

When the user choses browser defaults and the theme value is “none”, the html element class is cleared as well as the local storage. But the “dark” class may be added back if the user his browser set in dark mode.

document.documentElement.classList.toggle("dark", window.matchMedia("(prefers-color-scheme: dark)").matches)

Also, themeswitch.js primarly checks the local storage or the browser preferences on every page load to add or not the dark class to the main document element.

document.documentElement.classList.toggle(
  "dark",
  localStorage.theme === "dark" || (!("theme" in localStorage) && window.matchMedia("(prefers-color-scheme: dark)").matches)
);

You may not want to use this manual switcher. In that case, just get rid of it in the footer, delete themeswitch.js and don’t forget to also remove the @custom-variant in tailwind.css without which the natural dark mode will not work.

RSS Feed

2025-10-15T00:00:00Z

RSS

Making the content from one website available to others is called syndication. There are several standard formats for this, and one of the most common is RSS, which stands for Really Simple Syndication. There are also other formats like Atom, which is widely used.

11ty RSS Plugin

The 11ty RSS Plugin is a plugin that provides a range of utilities that are useful for generating an RSS or Atom feed using the Nunjucks templating syntax.

Huwindty comes with the RSS plugin and a feed layout that generates an Atom feed at the root of your site. On this demo site, it is available at aloxe.codeberg.page/huwindty/feed.xml.

How does it work?

The installation of this feed follows the 11ty documentation and uses the Nunjucks layout feed.njk to shape the feed as desired:

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:base="{{ meta.url }}">
  <title>{{ meta.title }}</title>
  <description>{{ meta.description }}</description>
  <image>
    <url>{{ meta.url }}{{ meta.image }}</url>
    <title>{{ meta.title }}</title>
    <link>{{ meta.url }}</link>
  </image>
  <link href="{{ meta.url }}{{ permalink }}" rel="self"/>
  <link href="{{ meta.url }}"/>
  <updated>{{ collections.documentation | getNewestCollectionItemDate | dateToRfc3339 }}</updated>
  <id>{{ meta.url }}</id>
  <author>
    <name>{{ meta.author.name }}</name>
  </author>

{%- for post in collections.documentation | reverse %}
  {%- set absolutePostUrl =  meta.url+post.url %}
  <entry>
    <title>{{ post.data.title }}</title>
    <link href="{{ absolutePostUrl }}"/>
    <updated>{{ post.date | dateToRfc3339 }}</updated>
    <id>{{ absolutePostUrl }}</id>
      <content xml:lang="{{ meta.language }}" type="html">{{ post.templateContent | renderTransforms(post.data.page, meta.url) }}</content>
  </entry>
{%- endfor %}

</feed>

Define your site’s metadata

You see that the code above used metadata that defines your site. It is set in the data folder under _data/meta.json.

{
  "title": "Huwindty 🌬️",
  "url": "https://aloxe.codeberg.page/huwindty",
  "description": "Huwindty enhanced template using 11ty.",
  "language": "en",
  "image": "/img/logo192.png",
  "author": {
    "name": "Alix Guillard",
    "fediverse": "@aloxe@mast.eu.org"
  },
"media_folder": "src/static/img",
"public_folder": "/img"
}

Choose which pages will populate your feed

The feed is using a collection. You can use the collection.all to include all pages to your feed but you may also like to share your blog posts or a specific area of your site. In this case you need to create the specific collection.

Create collection with tags

As the 11ty collection page states, you can create a collection of pages by adding a tags key in the front matter of the chosen pages. They will then be part of the collection with the same name as your tags.

tags: post

Create collection with the API

You can also create the collection programatically by using the collection API and setting it in your eleventyConfig. As an explample, the default Huwindty feed gathers documentation pages that are defined in eleventy.js from the path to the documentation folder.

// Collections 
eleventyConfig.addCollection("documentation", function (collection) {
  return collection.getFilteredByGlob("./src/pages/documentation/**/*.md");
});

The collection API documentation shows various examples of generating a collection.

The date

The feed is loading pages in reverse order with the most recent page on top. You want to make sure you know on which date is your page last updated by adding a date key in the page’s front matter. Otherewise eleventy will use the file date which may not be handy.

You can use different date format but I recommand using a simple YYYY-MM-DD everywhere. The date is then converted to a format accepted by RSS readers thanks to the dateToRfc3339 nunjuncks filter.

If you update a post and change the date in the front matter, the feed will be updated accordingly and the post will rise up in your feed.

Markdown

2025-10-15T00:00:00Z

Markdown

Markdown is a lightweight markup language that allows you to create formatted text using plain text syntax. It is easy to read and write and is often used with 11ty.

Pages using markdown are the same as html pages, they use the same front matter, but the content is written in markdown. The file extension is .md.

Markdown configuration

In this starter, 11ty is parsing markdown with markdown-it to generate the html pages. The configuration for markdown-it is in eleventy.js.

const mdit = require('markdown-it');
const mditAttrs = require('markdown-it-attrs');
const hljs = require('highlight.js/lib/core');

module.exports = function(eleventyConfig) {
  const mditOptions = {
    html: true,
    breaks: true,
    linkify: true,
    typographer: true,
  }
  const mdLib = mdit(mditOptions).use(mditAttrs)
  // Load any languages you need to highlight
  // (...)
  // highlight codeblocksaccording to language
  // (...)
  // generate responsive images from Markdown
  // (...)
  eleventyConfig.setLibrary('md', mdLib)
}

Plugins

markdown-it accepts additional plugins that help markdown meet your needs.

The following plugins are included in the default configuration:

markdown-it-attrs

This plugin allows you to use attributes in markdown syntax. For example, ![image](image.png){.logo} will output image.png, alt="image" and class="logo" in the html.

Some examples are available in Add HTML classes to 11ty markdown content.

Extra styles in markdown are explained in detail in the style section of this documentation.

highlight.js

This plugin allows you to highlight the code in a code block according the language. For example,  ```javascript will output <pre><code class="language-javascript"></code></pre> in the html.

The highlights can be themed, using a stand alone css in src/_assets/public/css/highlightjs.css. It is a copy of atom-one-dark.min.css. It is imported from src/layout/includes/head.njk and you can decide to import it from a CDN if you want.

Other themes are available. Check the way they look in the highlight.js example page and download them from the CDN or directly from the highlight.js repository.

You can also define your own theme following the guide from highlightjs.

accessibility fix

Code blocks in markdown are styles with a <code> nested in a <pre>. highlight.js applies the theme with styles on the <code> which always receives a display:block;. Because of this, when the code in the block overflows, the scrollable region is <code> instead of <pre> that could catch the focus.

It is important that scrollable region can be focusable to allow users without a mouse to scroll with the keyboard.

It is easy to fix this issue by removing pre code.hljs{display:block; in highlightjs.css and adjust the styles to make it look good but it would need to be done each time the them is changed with a new css.

Instead, I chose to make <code> focusable by adding the attribute tabindex="0". This is done in eleventy.js with mdLib.renderer.rules.fence, the markdown-it function that defines the html generated for code blocks.

Pitfalls

nunjucks code in Markdown

Markdown may be limited to achieve some of the custom rendering. To solve this you can include some nunjucks code inside markdown. You can read a few examples of this powerful solution in Custom Markdown Components in 11ty.

On the other end, this is not possible to directly add nunjucks code quotes in markdown code blocks. To make this possible, you need to change the template engine from nunjucks to markdown, adding templateEngineOverride in the front matter of the page you want to add the nunjucks code.

templateEngineOverride: md # for when you have njk in code blocks

This is explained in detail in Eleventy: Escaping Nunjucks Statements in Markdown Code Blocks

Note that this option is not added in the default pages when they are created by the CMS.

Images

Markdown is not known to be flexible with styling images, but you find a workaround for most of your wishes. There is an extensive blog post about the matter in How to Style Images With Markdown.

Responsive images

Markdown images are automatically rendered as responsive. A specific chapter on responsive images explains how this 11ty starter manages responsive images.

Content Managment System

2025-08-27T00:00:00Z

Sveltia CMS

Sveltia CMS is a content management system (CMS) designed to provide a user-friendly interface to manage content for static site generators. It is firstly created to be hosted by Netifly. It offers a clean and accessible interface to create and edit pages that are still saved as files on the git repository of your project.

Sveltia CMS is a complete reboot of Netlify CMS whose development was discontinued in 2022 and then rebranded in 2023 under the name Decap CMS. Since Sveltia CMS aims to offer all features of the original CMS, there is alost no difference between the two in terms of feature and configuration. For this reason, it is possible to follow the Decap CMS documentation while using Sveltia CMS.

Sveltia CMS is a single-page app that is pulled from the page you decide to add it too. In this starter it is available in the typical /admin part the public site. Nevertheless, you will need to go through a few steps before you can take advantage of it.

Authentication

Because new content is saved as files on the git repository of your project. You need to have a user that has access to your git repository. For this you will need to create and OAuth Application and set up your git forge to authenticate. The steps described bellow are using OAuth and github.

Create OAuth Application on github

Go to the Github OAuth settings from Settings > Developer Settings > OAuth Apps > Generate New.

Fill Homepage URL with the url of where you will install your external OAuth client. Authorization callback URL will get the same url followed by ‘callback’ https://example.com/callback.

Then hit on the button [Register application].

On the next step, you will have to create your Client Secret (CLIENT_SECRET) and save it in a secure file. Also save the Client ID (CLIENT_ID).

Build an external OAuth client on your server

In Netify, you can set up all you need to deploy and host your site. Netifly will manage your authentication and will let you maintain your site with Sveltia CMS.

If you want to deploy your site elsewhere, you will need an external OAuth client. Decap documentation has referenced a list of external apps you can install on your own server. This is the trickiest part of Huwindty as it will stand as a standalone app that your CMS with connect to for authentication purpose.

I chose two apps for this purpose, one is running on node and is served by nginx and the second is a PHP app served by Apache.

Run netlify-cms-github-oauth-provider on nginx

netlify-cms-github-oauth-provider is available on github and can run locally as well as on a server with nginx as a reverse proxy. The README is well details to run the installation.

git clone https://github.com/vencax/netlify-cms-github-oauth-provider
cd netlify-cms-github-oauth-provider
npm install

The configuration can be set in an .env file but can also be part of the launch command line.

NODE_ENV=production
ORIGINS=www.my_organisation.com,www.my_organisation_second.com
OAUTH_CLIENT_ID=f432a9casdff1e4b79c57
OAUTH_CLIENT_SECRET=pampadympapampadympapampadympa
REDIRECT_URL=https://your.server.com/callback
GIT_HOSTNAME=https://github.website.com
PORT=3111

Before you run the service, you need to set up the nginx for your OAuth domain to act as a reverse proxy.

location / {
	proxy_pass http://localhost:3111/;
	proxy_http_version 1.1;
	proxy_set_header Upgrade $http_upgrade;
	proxy_set_header Connection Upgrade;
	proxy_set_header Host $host;
}

The README also explains how tho set the redirections for auth and callback in the nginx configuration.

 location /auth {
    proxy_pass http://127.0.0.1:3111;
    proxy_pass_request_headers      on;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header Early-Data $ssl_early_data;
}

location /callback {
    proxy_pass http://127.0.0.1:3111;
    proxy_pass_request_headers      on;
    proxy_set_header   X-Real-IP        $remote_addr;
    proxy_set_header   X-Forwarded-For  $proxy_add_x_forwarded_for;
    proxy_set_header Early-Data $ssl_early_data;
}

After you run the service, you should be able to authenticate from your own server.

npm start

To make sure the service always run on your server, there are a few additional steps that I won’t detail here. However you can look at this article that details a solution with forever and crontab.

Run netlify-cms-oauth-provider-php on Apache

I chose the PHP Netlify CMS GitHub Oauth that comes with a blogpost explaining in detail how to set it up.

In short, you will have to clone the repo and install the dependencies:

git clone https://github.com/mcdeck/netlify-cms-oauth-provider-php
cd netlify-cms-oauth-provider-php
composer install

You will then have to copy the .env file into a new .env.local where you will add the CLIENT_ID and CLIENT_SECRET and callback url from the OAuth Application that you previously created on github:

OAUTH_PROVIDER=github
...
OAUTH_CLIENT_ID=CLIENT_ID
OAUTH_CLIENT_SECRET=CLIENT_SECRET
REDIRECT_URI=https://oauth.example.com/callback
ORIGIN=https://host.example.com

The line with ORIGIN is the host url of your site. Do not include any path or trailing slash on ORIGIN or the authentication flow will not redirect to your back-office

You will then have to upload everything from netlify-cms-oauth-provider-php onto your server. Your server must handle https and php. The root index should point to the public folder but all other folders should remain there.

When correctly installed, the index page of your Auth site should say ‘‘Hello’’ and offer a link to ‘‘Log in with Github’’. The current starter kit has a link to “My login with Github”.

User management

When you use github as authentication provider, users of your CMS will need an account on github and will use it to identify themselves. In order to access the repo, and be able to edit, they need to be given access to your website repository through settings > collaborators.

All users will be visible from there so users can be managed on github.

Users can check that they keep access to the repository by editing files. They can also check that the authorisation can access their account. On their profile > settings > *applications*.

The back office configuration

The back-office already installed with huwindty. You can find it under _assets/public/admin. This folder contains two files: index.html and config.yml.

The index.html is the page that will load the CMS application.
config.yml is the config file. You can update it to set the behaviour of your CMS.

If you prefer to use Decap CMS over Sveltia, simple uncomment the line in index.html, where the decap script is loaded and remove the one for Sveltia.

Define backend

In the backend: section of the config, you will document all details for Svetlia CMS to access and update your git repository.

The name will be the forge system that you use. Currently, Svetlia supports github and gitlab, but the current starter uses github.

  name: github # current huwindty has been tested with github only

The repo will be the path to the git repository of your huwidty site on the chosen forge.

  repo: aloxe/huwindty # Path to your GitHub repository

You need to specify the branch where the changes will be committed The branch has to exist on your repository otherwise the CMS will return an error.

If you choose your main branch, all changes that you save in the CMS will be pushed to the main branch and therefore, if the publication pipeline is in place, will be directly visible on your site.

Since Svetlia doesn’t yet handle content workflow, it is recommended to create a secondary branch for edition that can go through editorial workflow through a pull request.

  branch: edit # name of the branch where edits will be pushed

The content shown in the back office will be the one from the edition branch. If this branch contains many changes that are not merged into your main branch, the back end might be very different from the public site.

Finally, before you can start, you will need to update base_url: with the url of the CMS OAuth provider you published as explained earlier.

base_url: https://oauth.example.com # Path to ext auth provider

Media folders

You may also change the media_folder where all images and media will be uploaded to. The last part, with the collections, defines what folders and pages are editable by the CMS as well as the fields that will be available in the CMS. Usually you will set here all variables that are present in the Front Matter of your pages.

In the current setup, I used media_folder: '' and public_folder: '//' to allow images to be saved in the same folder as the page.

Once the CMS is installed, you can go to your website admin section. (i.e. https://aloxe.github.io/huwindty/admin/), and once you are authenticated with your github account, you can start edit the pages that are in your config file.

Editable content

The editable content is defined in the collections:. It allows you to list which Eleventy page in Eleventy will be editable, describe their properties and define which fields can be modified in the CMS back-officeinterface.

For example, the documentation pages of Huwindty are defined like this:

collections:
  - name: "documentation" # Used in routes, e.g., /admin/collections/blog
    label: "Documentation" # Used in the UI
    folder: "src/pages/documentation" # The path to the folder where the documents are stored
    thumbnail: /img/vera.jpg
    columns: [title, date]

With media and public folder following the documentation of Decap CMS:

    media_folder: '' # start with a slash
    public_folder: /documentation

Each page of this collection will have a layout called “base” and isMarkdown set to true. These will not appear in the CMS but will be set in the front matter. Then the title and headline can be modified as a string in the CMS.

    create: true # Allow users to create new documents in this collection
    fields: # All the fields for each document, usually in front matter + body
      - label: "Layout"
        name: "layout"
        widget: "hidden"
        default: "base"
        preview: false
      - label: "isMarkdown"
        name: "isMarkdown"
        widget: "hidden"
        default: true
        preview: false
      - label: "Title"
        name: "title"
        widget: "string"
      - label: "headline"
        name: "headline"
        widget: "string"
        required: false

User management with github

In your repository settings on Github, go to settings > collaborators and click on the button [Add people]. You will be able to add any github user as collaborator. Only people that you added will be able to edit your pages and you can revoke them at any time by removing them from the list.

Images

2025-01-04T00:00:00Z

Image location

With the Huwindty starter, images are stored within the content (after all, images are content too). They can be added in any folder and their URL will always be relative to the pages folder, which is the root folder for content.

Example image

For example, the image above (boat.jpg) is located in the /src/pages/documentation/ folder and is used by a page in the same folder. The URL used to display it on the page will be /documentation/boat.jpg. Always use an absolute URL for the image source (starting with a /).

Responsive images

Web pages can be displayed on any screen, from a small phone to a large high-definition, expensive monitor. Displaying a 3000px-wide HD image on a phone is a waste of resources that slows down page rendering. Conversely, showing a 150px picture on a wide monitor might miss some details. Making images responsive is how you provide the appropriate picture to each screen.

The article Responsive images 101 covers everything you need to know about this topic when managing a website.

Default choice

The eleventy config provides a way to generate responsive images and store them in the correct location, as well as generating the correct responsive code to use them (see .eleventy.js). In Huwindty, image sizes and formats are set using the following default settings and can be adjusted according to your layout and needs by changing the Images enum at the beginning of .eleventy.js:

const Images = {
  WIDTHS: [426, 460, 580, 768, 1200], // sizes of generated images
  FORMATS: ['webp', 'jpeg'], // formats of generated images
  SIZES: '(max-width: 1200px) 70vw, 1200px' // size of image rendered
}

Markdown pages are parsed with mdLib and images are handled with the mdLib.renderer.rules.image rule. Then the eleventyImageTransformPlugin plugin takes care of rendering the responsive code as defined using eleventy-img.

It is even simpler in HTML pages, as the eleventyImageTransformPlugin plugin takes all images in the code to make them responsive. Even images in the layout files are handled.

It is also possible to use the shortcode defined in eleventyConfig.addShortcode("Picture"…. This method allows you to define several options to display the image. Only the alt attribute is compulsory, but you can also override the default width and formats of your image to fit the specific design of your HTML page.

Responsive picture shortcode

To get a step-by-step understanding of how the eleventy-img plugin is used to create a shortcode that generates the images and provides the correct code, you can read How to optimize images on eleventy (11ty), which has been freely adapted for Huwindty. You may want to add lazy loading and the blurry effect if you wish.

An example is available on the Huwindty home page

    {% Picture page, "vera-davidova.jpg", "Photos of high grass dancing in the wind at the golden hour", undefined, undefined, undefined, undefined %}
    <!-- 
    Picture attributes: 
    page, file name, alt text, class, widths, formats, sizes 
    -->

The attributes are as follows:

page provides the current path to generate the correct output path. Simply use page after Picture, and it will be fine.
file name: In this example, there is no path to the image file since it is in the same folder.
alt text is compulsory for various reasons. I also encourage you to write nice descriptive text that really helps visually impaired users understand your image.
class adds a CSS class to the image so you can change its position and dimensions. The specific class lazy will also make the image lazy-load.
widths will override the default widths for which the output images will be generated. This is particularly useful if you change the image size using a CSS class; you will want to generate images of the same size.
formats will override the default formats.
sizes will override the default sizes to tell the browser how large the image will be before it is fully downloaded. The default is 100vw, but if you know your image will be displayed on half of the page, you may want to change this to 50vw.

Responsive Images in Markdown

For Markdown, we implemented what is explained in Responsive Images in Markdown with Eleventy Image, a nice step-by-step blog post explaining how to use markdown-it to parse normal image code in Markdown to generate responsive image HTML code using eleventy-img.

The image below is generated with the simple code

![drooderfiets and red circus](/documentation/circus.jpg){.lazy}

When you inspect the generated code, you see following responsive HTML:

<picture>
    <source type="image/webp" srcset="/documentation/images/circus-350w.webp 350w, /documentation/images/circus-700w.webp 700w, /documentation/images/circus-750w.webp 750w, /documentation/images/circus-1200w.webp 1200w, /documentation/images/circus-1500w.webp 1500w, /documentation/images/circus-2000w.webp 2000w" sizes="(max-width: 400px) 380px, (max-width: 470px) 450px, (max-width: 841px) 640px, (max-width: 1100px) 640px, 764px">
    <img alt="drooderfiets and red circus" class="lazy" loading="lazy" decoding="async" title="" src="/documentation/images/circus-350w.jpeg" width="2000" height="1500" srcset="/documentation/images/circus-350w.jpeg 350w, /documentation/images/circus-700w.jpeg 700w, /documentation/images/circus-750w.jpeg 750w, /documentation/images/circus-1200w.jpeg 1200w, /documentation/images/circus-1500w.jpeg 1500w, /documentation/images/circus-2000w.jpeg 2000w" sizes="(max-width: 400px) 380px, (max-width: 470px) 450px, (max-width: 841px) 640px, (max-width: 1100px) 640px, 764px">
</picture>

Lazy loading

Lazy loading images defers their loading on the page until they are actually needed, instead of loading these resources as soon as the page loads. This improves initial page load performance and enhances the user experience.

It is not recommended to lazy-load images that are visible on screen when the page loads (above the fold), but it is possible to defer images that are lower down the page. They will then be loaded as the user scrolls down.

Because of this, not all images can be lazy-loaded by default. Instead, content editors can intentionally request lazy loading by adding "lazy" as a CSS class. The responsive image script will add loading="lazy" to the output code.

The markdown example above shows how to add this class to an image in Markdown.

Non-responsive images and layout

As mentioned earlier, images in layout files such as head.njk are also handled and made responsive. Huwindty does not have images in its layout, but you can add images to them that will be displayed on all pages using the layout file. These images will also be automatically responsive.

If you want an image that keeps its width and format regardless of screen size, you will have to add the attribute eleventy:ignore. Eleventy will then bypass this tag and eleventyImageTransformPlugin will not make it responsive. This is quite useful for top-left logos, profile avatars or small icons.

Images in CMS

This starter comes with the simple Svetlia CMS that allows you to add, remove and update pages and media. Images in Svetlia CMS can be added in two ways:

in a dedicated media folder
(All images are available for all pages)
in the folder of the current page
(Images are not reusable in other pages)

Because the CMS uses Markdown and that images in Markdown are automaticaly converted in responsive pictures, there is nothing else to do other than choose well your images, organise them, and never forget the alt text.

Thumbnail

The thumbnail of a page is defined in the front matter. For example the current page has:

thumbnail: boat.jpg

This image is shown in the list of pages in the CMS interface, to help you netter spot the content you want to edit.

It is also used as the metadata image of the page. This is for example, the image that will be visible in the snipet when you share the url of a page on social medias.

Continuous Integration

2025-01-04T00:00:00Z

Github Continuous Integration

This starter comes with 3 github pipelines that can be used for your project’s continuous integration.

Deployment to github pages

pipeline: pages.yml
prerequisites: In your repository settings, you need to set github-pages as a new environment.

The pipeline is triggered on every update of the default branch. it will deploy the static site generated by 11ty (in _site) to github pages that will make it available at https://<your_account_name>.github.io/<your_repository_name>

If you choose this solution to publish your site, remember that the url in the meta.json needs to be updated with your_repository_name. Also make sure this name is saved in the env variables as BASE_HREF.

More on Github pages: https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site

Deployment to codeberg pages

pipeline: .woodpecker.yml
prerequisites: Access to woodpecker, codeberg’s CI platform, with set up to access your repository and saved secrets. Your repository should also have a pages branch.

The pipeline is triggered on every push on the main branch. It will generate the 11ty static site and commit it to the branch pages. Fron there, codeberg will publish it to https://<your_account_name>.codeberg.org/<your_repository_name>

Steps

apply for codeberg CI access
Generate an access token for your account
On ci.codeberg.org, add a repository, click the gear and add secrets.
woodpecker secrets

Deployment on a standalone server

pipeline: test.yml
prerequisites: You need to set up your own web server accessible via ssh.

The pipeline is triggered on every update of the branch called test or manually in the apropriate github action page ‘Deploy 11ty test 🛠️’.

It will copy the static site generated by 11ty (in _site) to the server of your choice using ssh.

To do so, you will need to create an ssh key pair and copy the public key to .ssh/authorized_keys. You will then need to save in your repository secrets all your server details:

HOST: the name of your server
USERNAME: your username
KEY: the private ssh key you just created
PORT: the specific port used by your server ssh daemon (if you use the default, it will be 22)

You can use duplicate the test.yml file and set as many pipelines as you want for exemple if you have multiple environement on various servers (staging and production for example). Then you can change the workflow_dispatch: section, the secrets as well as the path of your html root document after target:.

Accessibility pipeline

pipeline: axe.yml
prerequisites: none

The Accessibility pipeline is triggered on every pull request, it will run Axe on the generated site and return the number of accessibility violations found. If any violation is found, the action logs lists the broblem with explainations on the accessibility rule that is violated. Note that axe only knows the generated html so it cannot tell you which line of your code is wrong.

The current pipeline only tests the homepage accessibility.

Please note that only 20% to 50% of all accessibility issues can automatically be detected. Manual testing is always required.

Lighthouse pipeline

pipeline: lighthouse.yml
prerequisites: none

Currently the lighthouse pipeline can only be launched manually. It returns errors that may not be fixable but may still provide useful information.

The pipeline will display the error for each test and a link to the lighthouse page that tells you what to do to fix it. If it is all green, you can merge your changes in.

The settings of lighthouse are done in lighthouserc.js at the root of the project. It is possible to add assertions to focus on certain aspects of lighthouse measurements or allow more flexibility.

The current project tests three pages. It is possible to add more, but be aware that adding too many pages may cause the action to time out.

More on lighthouse-ci: https://github.com/GoogleChrome/lighthouse-ci/blob/main/docs/getting-started.md

You can also chech your live site on Lighthouse directly on pagespeed.web.dev

Documentation

2024-12-29T00:00:00Z