Storyblok is an easy to understand and to work with CMS. It comes with a Digital Asset Management, and a powerful Image Optimisation API. For daily use on your website, there is only one small problem with this: the domain for the assets points to a.storyblok.com. Not everyone is happy with that, you might want to load assets from your own domain.

Why

There are a bunch of tutorials on how to set up your own asset domain with Amazon CloudFront or Azure or Google Cloud - but there is a much easier way. Especially when you don’t want to add into Infrastructure or you are not a customer of any of those services this alternative can be quite interesting.

The setup

Chances are, when you operate a website, you have a web server running*. My personal preference is nginx, but that is to everyone for themselves to decide. As I know nginx better than the alternatives, I will give a quick example on how to achieve this.

The way you do it is that you set up a reverse proxy, as such:

proxy_cache_path /var/www/asset_cache levels=1:2 keys_zone=asset-cache:500m inactive=60m;

server {
        listen   443 ssl http2;

        server_name assets.mydomain.tld;
        root /var/www/html;

        # adapt this to your SSL config
        ssl_certificate /etc/letsencrypt/assets.mydomain.tld/fullchain.cer;
        ssl_certificate_key /etc/letsencrypt/assets.mydomain.tld/assets.mydomain.tld.key;
        ssl_protocols TLSv1.3;

        location / {
                proxy_ssl_server_name on;
                proxy_cache asset-cache;
                proxy_pass https://a.storyblok.com;
                proxy_pass_request_headers on;
                add_header X-Cache-Status $upstream_cache_status;
        }
}

And that’s it.

In your front end, add a helper to rewrite the asset URL such as this

function transformImageSrc(src) {
   const url = new URL(src);
   if (url.hostname === "a.storyblok.com") {
       url.hostname = "assets.mydomain.tld";
   }
   return url.href;
}

(From the Storyblok Documentation)

Congratulations, you’ve just set up your own asset domain – but using this setup we can even dial it one bit further. What if we you want to load images from a folder like “/assets/”? The answer is: the setup needs to change only slightly:

proxy_cache_path /var/www/asset_cache levels=1:2 keys_zone=asset-cache:500m inactive=60m;

server {
        listen   443 ssl http2;

        server_name www.mydomain.tld;
        root /var/www/html;

        # all your normal webserver configuration

        location /assets {
                proxy_ssl_server_name on;
                proxy_cache asset-cache;
                proxy_pass https://a.storyblok.com;
                proxy_pass_request_headers on;
                add_header X-Cache-Status $upstream_cache_status;
        }
}

And in the frontend change your helper to

function transformImageSrc(src) {
   const url = new URL(src);
   if (url.hostname === "a.storyblok.com") {
       url.hostname = "www.mydomain.tld/assets";
   }
   return url.href;
}

Tada.

You might want to play around a little with different parameters and settings, the documentation for nginx reverse proxy can be found here: https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/

Other web servers

Other web servers also allow you to set up reverse proxies. I haven't tested it, so your mileage may vary.

• Apache: https://httpd.apache.org/docs/2.4/howto/reverse_proxy.html
• Caddy: https://caddyserver.com/docs/caddyfile/directives/reverse_proxy
• Traefik: https://community.traefik.io/t/traefik-as-reverse-proxy-server-to-external-web-server/15619/2

If you have anything to add or correct - reach out on Mastodon (@gurkendoktor@mastodon.cloud)

* If don’t have one because you run your site on e.g Netlify, there might still be a way to set up a proxy. For Netlify, this is described here: https://docs.netlify.com/routing/redirects/rewrites-proxies/

I cannot count anymore how many times the reverse proxy function of nginx has saved my life - or sanity - in course of the last year.

Like every life-saving, close-to-magic technology, it needs mastery. Which I do not command, thus having to spend endless nights fiddling around for the little joy of "it works".

One pitfall is that you cannot seem to use sub_filter (which replaces a string with another string) on compressed resources. Which is a bit of a bummer but at least there is a workaround: set an empty accept-encoding header. I found it here.

Replace URLs with nginx sub_filter

Replacing URLs in content served behind nginx reverse proxy

Martin CosgraveMartin Cosgrave

But why am I so excited? Just a small example:

In my current scenario, I have a setup that generates a folder structure like this:
domain-like-folder/subfolders/of/content
with language automatically prepended, meaning
language/domain-like-folder/subfolders/of/content

What I need is
domain.tld/language/subfolders/of/content

I set up a server with the above domain folder structure on a server called origin.tld. Then I configure domain.tld like this (simplified):

 location /language/ {               
  proxy_pass https://origin.tld/language/domain-like-folder/;
  proxy_set_header Accept-Encoding "";
  sub_filter   /language/domain-like-folder/   /language/;
  sub_filter_once off;
}

The sub_filter directive is necessary (and also a big part of the magic), as the generated links on the origin domain would look like this: <a href="/language/domain-like-folder/other-subfolder"> which is what I'm trying to avoid. Of course, you can use sub_filter much more sophisticatedly than I do here.

You know better? Write to me! @gurkendoktor@mastodon.cloud

I haven't posted in a while. That happens. A few posts will follow this one in the near future. Not all of them will be about nginx. Some will be about Astro, 11ty, Headless CMS, or other random stuff.

It is Friday evening, a bunch of campaign landing pages on Eloqua are about to be launched, and suddenly no images are being loaded. Instead, a “warning” is displayed. What happened? And what does it mean? Can it be solved?

Prerequisites

Let’s take a look at the setup first. On client side, I’m using an iPhone 11 Pro with iOS17, pretty much stock, and Safari in Private mode. I live in a country where Private Relay is not available, so this is not enabled.

On the server side, the pages are hosted as landing pages in Eloqua. Eloqua is a marketing automation system by Oracle, and one of the key players in the martech industry.

When you are using Eloqua, there is an option to use your own (Sub)domain with Eloqua, which is basically achieved through CNAME DNS entries. These can be also used for assets such as images etc. So instead of the generic asset domain img06.en25.com the domain would be something like assets.myELQdomain.com. Other, similar solutions, have a similar option that works a similar way. It is safe to say that this is “industry standard”. This was also the setting of the landing page in question.

The issue

When loading the page, things got interesting. Using pages.myELQdomain.com/page would present the landing page, but every request to assets.myELQdomain.com would not be responded to. Changing the image URL to img06.en25.com however would immediately load the image, so it can’t be an issue of blocked content.

While trying to find an answer, I’ve tried different proxying methods to see the phone’s network traffic. The moment I used a proxy, the problem would not occur. “Sus”, as they say. The same problem happens when I reference the images on a website outside the Eloqua environment (or at least the myELQdomain.com). That makes it is really hard to investigate what’s happening here. But at least we know that the very interesting way of naming images – the generated file name has curly brackets – is not the culprit.

CNAME cloaking?

The first suspicion was a prevention of CNAME cloaking. CNAME cloaking means setting up a subdomain.mydomain.tld DNS entry which points to tracking.adtech.tld and is a common technique to keep 3rd party cookies alive. For everyone interested in a deeper read, here is a paper about CNAME cloaking – or you read it in a simpler fashion in a blog post from NextDNS. Every tool that supports privacy (ad blockers, Pi-Hole, privacy conscious VPNs) have lists to prevent this, and basically either blocks the request from being sent, or resolve the domain subdomain.mydomain.tld to the server 0.0.0.0 or NXDOMAIN instead of the original entry, preventing 3rd parties from tracking you.

The suspicion for this being the reason arose as the assets domain is resolved to a CNAME which is resolved to another CNAME to another CNAME to the Akamai edge. That can however not be the (only) case, as for opening the image in a new tab would work. So it cannot be (only) that. What else can it be?

Private DNS?

The next suspicion was triggered by those 2 articles:
[https://help.nextdns.io/t/q6yq4xy/nextdns-stops-working-properly-when-updating-to-ios-17-ipados-17]
[https://news.ycombinator.com/item?id=36245362]

The private mode of iOS17 is using the Apple DNS server, thus enabling Private Relay through the back door. Interesting. And not possible to inspect (for me!), as this is based on QUIC and DNS over HTTPS. The moment you add a “man in the middle” (like a debugging proxy) everything  is resolved normally. It also does not happen on MacOS, even though Safari 17 for macOS should have the same measures as its iOS sibling.

But again, opening the image in a new tab works, so it can’t be that. Or not alone.

Another possible reason

Headers. The page is sending the request with a Sec-Fetch-Site: same-site header, whereas it is sending Sec-Fetch-Site: cross-site to the imgXX domains. This makes sense, and the behaviour would make sense if the seemingly same site is resolved to what is a cross-site request header.
As the headers show the same behaviour when trying to reproduce it in an external setting, the problem is not reproducible anymore.

A combination. None of the above alone seems to cause a problem. That makes it harder to detect, but also easier to circumvent.

How can I avoid it?

Host assets externally

Loading assets like images, CSS etc from an asset server does not seem to trigger the issue. So if you can, do that. It can be as easy as an AWS S3 bucket, or a bare metal nginx static web server. Your assets also may load faster, and you can fine tune the loading performance.

Host the pages externally

Let the landing page live outside Eloqua. You can still load the assets from Eloqua. This decreases the probability your page to run into a content blocker like uBlock Origin. On the other hand, it makes you miss out on the features of Eloqua like the block builder or easy form integration. You would need someone with deeper technical knowledge or a developer to help you here, especially transferring and connecting forms and actions. Delivering gated content is also changing.

Quick fix: change the URL

Open your landing page in the code view and replace every occurrence of assets.myELQdomain.com with img06.en25.com (or whatever the corresponding default for your Eloqua instance is). This might be cumbersome, but it is a quick solution.

What will the future bring?

The problem occurred on iOS17 in a private tab. It is said that approx. 20-35% of users use a sort of “incognito” or “private” mode to surf the web. However, the setting to use the same “non-tracking behaviour” in all web browser tabs, is very easy to reach, and activation is highly encouraged.  With the usually very fast adoption of new iOS version, it can be approximated that within the next 6 months 30% of all iOS traffic will see this behaviour. So ultimately, the root cause of this should be found out to see how it can be dealt with in a more sustainable manner.

In the first part of the series we’ve configured Eleventy to use flexible modules which bring all their own layouts and assemble them to a single page. Now let’s crank it up and make it even more flexible and useful.

Next steps (this part)

First of all, we still need to sort the modules in a way that they make sense and tell a story, to bring them into the correct order (or any order at all).

Our second task is to create multiple pages within one site with the same approach, so that we’re not limited to building single-page websites – and from there we will take a quick detour into building similar sites from with content shared between them.

While we touch things, we will also clean up the code (actually the content) a little, so that it is easier to understand and maintain.

Sorting items

When we left off, we’ve had a modular landing page with configurable modules that can have different appearances. The content is still a little unorganised, though. Let’s fix that first.

We want to display the modules in a certain order. We could achieve this by naming the modules accordingly, and rely on the file system’s capability to do it as we need it. Or we make this a little more reliable, with one of Eleventy’s custom filters. I found the solution here, Eleventy docs about sorting can be found here. You can also use as file name based sorting approach, you have to configure your collection accordingly.

What we want to achieve though is to sort all sections by their displayorder front matter property, and then pull out whatever we need.

    config.addCollection('sections', collection => {
        return collection
            .getFilteredByTag('section')
            .sort((a, b) => (Number(a.data.displayorder) > Number(b.data.displayorder) ? 1 : -1));
        });    

One small trick: if your layout still needs to be flexible, you can use increments of 10 between each section and leave some space to easily add sections inbetween without having to renumber everything. A bit like back in the days when we were using line numbers for programming.

Building multiple pages, together

So far, we’ve built one page with different sections. That’s fine for a landing page, but even landing pages tend to consist of multiple (sub-)pages. So let’s build multiple pages with our existing approach.

Multiple pages

Creating multiple pages in principle is easy with Eleventy. You create one Markdown file for each page you want to build, and you’re mostly fine. Eleventy will build the structure for you, and make it all accessible to the pagination functionality. Pagination is a mighty tool. However, we are not talking about pagination today, instead we will use a slightly different approach.

To recap, this is our landing page:

---
title: "My Awesome Landing Page"
layout: "layout.njk"
header:
  heroImage:
  mainHeadline:
  secondaryHeadline:
  primaryCTAText:
  primaryCTALink:

footer:
  companyName: "Awesome, Inc."

config:
  date: 2022

---

We want only a few, distinct pages, that we can link “manually”. So let’s introduce a new piece of data and call it pagealias. You could use the slug of the page here or pretty much anything, as long as it is unique.

In the markdown file, we need to change two things: to our index.md file, we’ll add the following:

alias: landingpage

In the markdown files of the modules or sections we want to be displayed on that page, we need to add something as well to connect them. We do it as such:

pagealias: landingpage

Now it is more obvious, to which page this belongs.

Depending on your preferences, you could map it to something existing (like the permalink), or be a bit more obvious and in the “master file” notate the pagealias too. I’ve chosen the second option here so the approach is more obvious.

Make sure reflect this in your template as such:

{% for item in collections.sections %}
	{% if item.pagealias == alias %}
		{% if item.data.layout %}

			{% include item.data.layout %}

		{% endif %}
	{% endif %}
{% endif %}

Now, only content relevant for this particular page will appear on it.

Next, let’s create a file aboutus.md

---
title: "My Awesome About Us Page"
layout: "layout.njk"
header:
  heroImage:
  mainHeadline:
  secondaryHeadline:
  primaryCTAText:
  primaryCTALink:

footer:
  companyName: "Awesome, Inc."

config:
  date: 2022

alias: aboutus
---

After that, let’s create a folder aboutus in our source folder, and add the following file aboutus1.md

---
title: "Simple text / image section for about us"
tags: "section"
layout: "modules/text-image-basic.njk"
headline: "All about us!"
image: "assets/images/awesome_team.jpg"
imagealttext: "An awesome image"
permalink: false
pagealias: aboutus
---
This is all about us. You can make it about anything you want, but it is really only about us.

When the build runs, you will see in your dist folder two files: index.html and aboutus.html – with the respective content on each page. Isn’t that great news?

There are some caveats to this. If your website contains a really awful lot of pages, and those contain a lot of section each, the “collections.sections” might hit hard on your memory, and nested loops may impact your build performance.

In the scenarios I’m using this for (approx. 100 pages), I don’t see any impact (Eleventy is blazingly fast!) but your mileage may vary. It would then also pose different challenges in regards of content organisation, but that’s not to be covered here.

DRY up

Let’s clean things up quickly, as we move forward. To do that, we apply the DRY principle here.

DRY stands for Don’t repeat yourself. That’s a principal that got famous with Ruby on Rails, and although it’s not always practical to stick to it by the book, it should be on the list of things to achieve – for once as multiple occurrences of the same code are harder to maintain and might introduce bugs through the back door.

In our case, it’s a bit more simple. We don’t want to litter our front matter with redundant information. So … let’s look at it. We have in every of our module’s front matter

tags: 
- section

pagealias: landingpage
permalink: false

To clean this up a little, Eleventy’s data model helps us. We put all our sections in a folder called sections, and within this place a sections.json with the following content:

{
	permalink: false,
	pagealias: "landingpage"
	tags: ["section"]
}

This would clear our frontend matter to quite an extent. One could argue that this is not a semantic use of tags, but tags in Eleventy are meant to structure your content both in a semantic and technical way – or do anything you like, really.

Re-purposing items

One of the things that you come across is that you have the same items re-appearing over the page. I want to quickly demonstrate a way to re-purpose items. This will get more important in Part 3 of the series, but here’s a start.

You can repurpose items in different ways. The path that we’re taking here is on module level – we’re building a module that uses shared content. With this approach, we have control where this module appears on the page on a page level. For repeating items that have a fixed position within the page structure, the approach might be different.

In our example, we will build a proof section. Because what we need for ultimate credibility is of course some proof from our existing customers, that everything is awesome, and they are the happiest. We choose here the “user quotes” section: “What our customers say”. We would need this kind of section towards the end of the landing page, and around the middle on the “about us” page.

First, let’s create a “shared” folder within our source folder, so we have a place for content that might be shared across pages. This is not necessary for Eleventy, only for us to find it more easily.

Within this folder, we create a “quotes” folder, wherein each Markdown file is one quote. An example would look like this, you can come up with more.

---
tags:
	- quote

avatarimage: https://thispersondoesnotexist.com/image
avatarimagealt: "an image of a random person, pretending to be our customer"
username: Klaus Kleinholz
quote: This building block system is awesome! I don't know how I could live without it before.
---

Next, we make all the quotes accessible in a collection.

    config.addCollection('userquotes', collection => {
        return collection
            .getFilteredByTag('quote');
        });    

Now, we have all the quotes in one place.

Then, we create the module layout file userquotes.njk:

<section class="section_userquotes">
	<h2>{{ item.data.title }}</h2>
	<ul class="quotes">
	{% for quote in userquotes %}
		<li class="quote">
			<img src="{{quote.data.avatarimage}}" alt="{{quote.data.avatarimagealt">
			<q>{{quote.data.quote}}</q>
			<h5>{{quote.data.username}}</h5>
		</li>
	{% endfor %}
	</ul>
</section>

We can even choose to make this configurable with parameters and assign this to only certain pages, but for now let’s use this one as is. We will come back to this in the next episode.

Finally, we need to create a module for each page in the corresponding content area (that is the sections folder and the aboutus folder).

---
title: "And this is what our customers say"
tags: "section"
layout: "modules/userquotes.njk"
permalink: false
pagealias: landinpage
displayorder: 7
---

And

---
title: "But enough about us, here's our customers"
tags: "section"
layout: "modules/userquotes.njk"
permalink: false
pagealias: aboutus
displayorder: 3
---

The items that we’ve already banished to the .json file are just displayed here for clarity. You can remove them if you have applied the above principle.

Multisite, shared content

So now we’ve got this done, let’s imagine the following scenario: you want to build multiple landing pages about the same thing – say a washer and a dryer. There are some differences, but also content items (or even whole pages) that these sites share.

There are Eleventy plugins that take care of that, e.g Eleventy multisite. However, I want to show a very simple approach. This is not a scalable approach by any means, and doesn’t cover edge cases, it is just how far you can get without having to know much about development.

To do so, we go back to a technique that we’ve been using before. Without big changing, we’re creating another alias which we call “site”. This can contain the whole domain, if you want – or just a shortcut / slug of sort. It just needs to be unique.

In our front matter, we add the site property to the initial document, and all the modules. This way, you make sure that information only displays on the sites you want to have it.

The only thing that we need to change is in our base template:

{% for item in collections.sections %}
	{% if site in item.data.site %}
		{% if item.pagealias == alias %}
			{% if item.data.layout %}

				{% include item.data.layout %}

			{% endif %}
		{% endif %}
	{% endif %}
{% endfor %}

(Note we’re using in here instead of == so that we can assign content to multiple sites.)

It might seem cumbersome to attach information to every different content item, but in the end this approach is not meant to be for a multisite with 1.000 pages each. It’s just for a small set of sites that ideally share content between them and are set up the same way. Otherwise you might want to either go a different route, or set up multiple projects individually.

To save the sites in individual folders, we need to modify the permalink in the front matter so that it would like this:

---
# …
site: site1.com
permalink: "{{ site }}/{{filePathStem}}/{{fileSlug}}/index.html"
# …
---

As a result, the generated pages would be available in dist/site1/…. There is a way that you can configure this in the .eleventy.js config file from Eleventy 2.0.0 onwards, which makes it again a bit easier.

There’s one thing missing though. Something important. We have not been dealing with any images or CSS so far. What is very easy understandable to start with is to just add a passthrough copy to the .eleventy.js config file.

The process is described in the docs for passthroughCopy.

Our file can look like this:

module.exports = config => {
    config.addPassthroughCopy("assets/**");
};

When we’re dealing with multiple sites however, things get a little more complicated. The most straightforward approach is to copy it into every single site folder. In a very blunt manner, we can add an after hook and perform a synchronous copy operation. So … let’s do that and start off with quickly creating a new collection of the site property with Eleventy’s custom filtering:

config.addCollection("sites", function(collectionApi) {
        return collectionApi.getAll().filter(function(item) {           
            return "site" in item.data;
        });
});    

Now we have a collection, but as I couldn’t work out how to access this in Javascript through build time, we need a slight addition as such:

//put these outside the module.exports section of .eleventy.js
const fs = require('fs')
const path = require('path')
let siteNames = new Array();

config.addCollection("sites", function(collectionApi) {
        // build our own collection based on the "site" property
        let sites = collectionApi.getAll().filter((item) => item.data.site);        
        
        //make collection contents available to the be accessed by overall config
        for(let i=0;i<sites.length;i++) {
            siteNames.push(sites[i].data.site);
        }

        //make collection available to eleventy
        return sites;
    });

    config.on('eleventy.after', async ({ dir, results, runMode, outputMode }) => {
       sitesNames.forEach(element => {
             fs.cpSync("./src/shared","./dist/"+element+"/shared",{recursive:true});
        });        
    });

Which will copy everything from the “shared” folder into the destination folder for the generated sites. If you have site specific assets, you can add something like this

sitesNames.forEach(element => {
        fs.cpSync("./src/shared","./dist/"+element+"/shared",{recursive:true});
		fs.cpSync("./src/"+element+"/assets/**","./dist/"+element+"/assets",{recursive:true});
        });     

You need to create a folder with the site name in thesrc folder, and after page creation everything will copied automatically. However, this does not trigger reload in an eleventy --serve scenario.

Summary

We’ve learnt how to extend our page to multiple pages and to sites, how to display things in a certain order and how to share content between pages and sites.

Next part

In part 3 we will extend what we have built so far and apply it for the scenario of A/B testing, and will also create a basic personalisation. With static pages? Yes, with static pages. This is where we would need a bit more than Eleventy, but I promise that no Javascript will be involved.

Addendum

I really can recommend you to go through the Learn Eleventy From Scratch website. Even if you might not need the “from scratch” part, some concepts are explained in a more practical and understandable way than in the docs. The docs are brilliant, but (by design) have the abstract, general approach whereas on that site you can find good examples of how things actually look like when you work with them. You then would need to backtrace from them to the overall concept.

In many digital marketing contexts, you would need “a quick landing page” for a product, a service, or something. It is a single page that would look something like this, consisting of a set of different content blocks / sections / modules / components – whatever you want to call it –, presenting content in different ways.

A decent numbers of web developers have been there, and for some it’s still their daily life. Everyone has their own approach to it, I’ve been looking for something flexible and scalable with a high Developer Experience and the possibility of a quick and reliable delivery.

I will show you in this series how to build a scalable page with the Static Site Generator Eleventy (11ty / 11ty.dev), how to build varieties of the same page (e.g personalisation or A/B testing) and how to extend this to a multisite environment. Another approach to the same problem is shown here https://github.com/ttntm/11ty-landing-page – see for yourself where the differences are and which approach suits you and your needs more.

Why Eleventy?

There are a lot of static site generators out there to choose from (for a good overview you can start here. (If you need an introduction to the general topic, look at “What is a static site generator?”) The choice can be made based on technology, hype cycle, existing infrastructure, or “other criteria”.

I have settled on Javascript as I have lesser experience with Go, Ruby, or Python – and PHP … well, is PHP. I use it and I don’t hate it, but in the overall Jamstack ecosystem it is not very prominent. Besides the fact, that PHP is a static site generator already.

While looking at the different options, these parts were the most important to me:

• any number of sections should be possible
• sections should have a configurable flexible appearance
• DRY (if possible)
• Markdown based (I might want to scale this to a headless CMS)
• No server or client side dependencies beyond the SSG itself.

Second tier criteria were:

• Availability of skills
• Learning curve
• Extensibility (multi-site / multi-language)

The not so important things were

• build support “on the edge”
• build times
• “native integration” (e.g into Netlify, Vercel, … )

Eleventy fulfils two criteria out of the box.

There is no framework dependency on client side, means we don’t need to ship Javascript if we don’t want to, which is always a big big plus in my book. Additionally, we are not subject to dependencies beyond Eleventy. That might vary for your use case, but I like to leverage the layers of the web to their full extent to build a robust experience.

You can use Markdown (amongst other languages) to store content.

Besides that, it’s blazingly fast and flexible, and I’ve read a lot of good things about it. But after so much ado, let’s get going.

Building the page

Given that content and design are ready, let’s build the page. We quickly start with setting up the page build environment as such:

src – the folder where our source files are. Layouts, content, images, media, everything has its place under this.

dist – here is where the rendered page lives.

Create a file .eleventy.js that looks like this:

module.exports = config => {
	return {
        dir: {
            input: 'src',
            output: 'dist'
        }
    }
};

If you prefer something different, you can change this in .eleventy.js

To learn more about setting up and configuring an Eleventy project, check the 11ty website or one of their great tutorials.

The layout(s)

The layout can be split into the main layout (base template, if you might), and the partials for the different parts of the page. The sections part plays a special role, but we’ll come to that.

The layouts live in a special folder, src/_includes.

The base / main layout

We start with the overall layout definition: layout.njk

<html>
	{% include "partials/head.njk" %}
	<body>
		{% include "partials/header.njk" %}
		{% include "partials/sections.njk" %}
		{% include "partials/footer.njk" %}
	</body>
</html>

The partials

The layout for the partials can all be found within the _includes/partials folder. You can put them wherever you want, you just need to let Eleventy know about this.

Let’s start with a very simple HTML head section in partials/head.njk:

<title>
	{{ page.title }}
</title>

After that, we define the header. It consists of two types of headlines, a big image and two CTAs (primary and secondary)

partials/header.njk

<header>
	<img class="image-hero-image" 
		 src="{{ header.heroImage }}">
	<div class="text">
		<h1 class="text-hero-primary">
			{{ header.mainHeadline }}
		</h1>
		<h2 class="text-hero-secondary">
			{{ header.secondaryHeadline }}
		</h2>
	</div>
	<div class="buttons">
		<a class = "button-cta-primary" 
			href = "{{ header.primaryCTALink }}">
			{{ header.primaryCTAText }}
		</a>
	</div>
</header>

The sections

For the sections, we use Eleventy’s collections feature. We could set this based on folders or tags, for the sake of simplicity we’re using the tag “section” for every section here. The file looks as follows:

partials/sections.njk

{% for item in collections.section %}

	{% if item.data.layout %}

		{% include item.data.layout %}

	{% endif %}

{% endfor %}

This iterates over all files that belong to the section collection, checks if layout data is present in the frontmatter and includes the corresponding file. This gives us a lot of flexibility in how the content can be set up for the individual module.

An example section layout could look like this:

modules/text-image-basic.njk

<section class="item.data.sectionClass">
	<div class = "container-section-image">
		<img class="image-section-image" src="{{ item.data.image }}" alt="{{ item.data.imagealttext }}">
	</div>
	<div class = "container-section-text">
		<h2>{{ item.data.headline }}</h2>
		{{ item.templateContent | safe }}
	</div>
</section>

Let’s create the template for the footer quickly, before moving on to the data.

partials/footer.njk

<footer>
	<div class = "footer-conversion-area">
		<!-- use your signup input here -->
	</div>
	<hr>
	&copy; {{ config.date }}
</footer>

The data

Let’s start with the main file, index.md. This holds all the page meta information, like title etc. as well as the “static parts” like content for the header and the footer. All of that is in the front matter.

---
title: "My Awesome Landing Page"
layout: "layout.njk"
header:
  heroImage:
  mainHeadline:
  secondaryHeadline:
  primaryCTAText:
  primaryCTALink:

footer:
  companyName: "Awesome, Inc."

config:
  date: 2022

---

So with that done, we’re moving forward to the sections. Creating a content section for the layout above in the sections/section1.md file.

---
title: "Simple text / image section"
tags: "section"
layout: "modules/text-image-basic.njk"
headline: "Most awesome feature"
image: "assets/images/awesome.jpg"
imagealttext: "An awesome image"
permalink: false
---
Amazing news for amazing people: **Our newest feature is now available for everyone.** You can see it in the other sections.
This is a second paragraph, it is only here for demonstration purposes.

There are 2 key things to note here:

The frontmatter carries a layout entry, just as any file would. This assigns the correct sectional layout to the content.

You might have spotted the permalink: false entry. This means, that Eleventy will not generate a separate page from this Markdown file as it normally would. Try to remove it and you’ll end up with a /sections/section1/index.html file.

Additionally, the “long copy” content is not part of the frontmatter. This retains the full power of Markdown to be used in your content creation, you could even add extra images etc.

So far, we have the header, footer, and one section. Let’s create a few more.

Flexing the sections

To be really flexible, we need to create some more, different sections.

Let’s start with the layout file: modules/video.njk

<section class="{{ item.data.sectionClassName }}">
	<div class="container-text">
		<h2>
			{{ item.data.headline }}
		</h2>
		{{ item.templateContent | safe }}
	</div>
	<div class="container-video">
		<video controls="yes" poster="{{item.data.posterimage}}">
			<source src="{{item.data.video}}" type="video/mp4">
            	Your browser does not support the video tag.
		</video>
	</div>
</section>

Now let’s create our content file: sections/section_video.md

---
title: "Video section"
headline: "Watch how it comes to life"
tags: "section"
layout: "modules/video.njk"
video: "my-video.mp4"
posterimage: "assets/images/my-awesome-image.jpg"
permalink: false
---
Here is additional content that accompanies the video. 

**See for yourself!**

We’d probably also want an image that can be full width (or not), with an annotation, so we create modules/full-image.njk

<section>
    <img src="{{ image }}" alt="{{ imagealttext }}">
    <caption>{{ imagecaption | safe }} </caption>
</section>

And the data file section-image.md:

---
title: "Simple image section"
tags: "section"
layout: "modules/full-image.njk"
image: "assets/images/awesome.jpg"
imagealttext: "An awesome image"
imagecaption: "A longer caption for <strong>this particular</strong> image"
permalink: false
---

So, the idea is clear. We’re carrying a layout section in every section along with the content. This enables us to have as many different sections as we want. This is the first step on building modular landing pages.

Conclusion

So far the ride has been smooth. We have now at our hands a simple and elegant way to quickly build an extensible marketing landing page. Especially when you have an existing component library or similar, it is very easy and very fast to set up pages in that way.

In its current state, this is only working to build one page, no links between pages and no “sub-pages”. After all, the first step was to build a flexible landing page and nothing more.

In the next step we will see how we can use this approach with different pages, page-specific content and content shared across sections and pages.

Another thing to keep in mind is that this is one way to achieve it. There might be many others, the same could probably implemented with some template logic and some clever CSS, but in my opinion this approach is more obvious and easier to maintain. And I believe that a good Developer Experience results in better products.

Thanks

To all the amazing people behind Eleventy (especially Zach Leat), to Stephanie Eckles and her 11ty.rocks which you should really have a deep look into.

Reminiscing a thing long gone, fighting against legacy systems, a way to collaborate, and a no-code tutorial for a website.

1. A trip down memory lane

Flash might be dead, but this week there was a few things that got a bit of the 2000s vibe back.

First, someone posted a Youtube clip of the old 2advanced website on Twitter.

YouTube has more of those, I find the later ones even more characteristic for that era – but go see for yourselves.

Then, a couple of times this Vice article about the creative era that flash coined, and I really recommend to read it. The whole thing deserves an article on its own, but whereas from the standpoint of a standardized open web Flash is much questionable, the whole era, the spirit, and what it kicked off is unparalleled.

As an aside, this article about Yahoo! Games and the role Flash played in it (and, to an extent, made it), is also a very interesting read.

2. Can i use for emails

All web developers (should) know caniuse.com, a page that shows the availability of CSS properties for every browser. Now this also exists for email development, and it basically shows that Outlook sucks. This is the biggest reason why email development is still so cumbersome.

3. Designer and developers: it doesn’t have to be hate

Brad Frost and Dan Mall continuously share their attempts on improving the collaboration between designers and developers. Their attempt is the Hot Potato Process, which sounds less fun than it seems to be.

4. Creating a page in Webflow

I have been made aware of webflow.io a couple of times now, and only heard much praise about it. I have only dipped my toes in the water, and didn’t get very far as of now. However, this tutorial might help me with that – it teaches how to create “a highly converting landing page”, which is a task that can be happily taken over by a a low-code person in a low-code tool. Almost like Flash back then ;)

Just a quick one, all the logs are going throughs an ELK stack now. Pretty proud, more to come.

I have realized that I should write more. One of the easier ways of getting (back) into the habit is summarizing things that have already been written. So I’ve set myself the goal of organizing the things I stumble across on a weekly basis, to keep them as a library to reference for myself and to make them available to whoever reads this here blog.

Part of the reason why I’m doing this is based on this tweet, which I couldn’t agree to more: https://twitter.com/usabilitycounts/status/1165717906849583104. Writing helps to structure the thinking, and ultimately the outcome.

Here’s the first post of this kind, and the one I hope to establish a long tradition.

1. Designing enterprise apps is not easy

In this blog post https://uxdesign.cc/how-white-space-killed-an-enterprise-app-and-why-data-density-matters-b3afad6a5f2a Christie Lenneville and Patrick Deuley describe the challenges they were presented with when redesigning an enterprise application that people use to get work done in large amounts.

They present us with the general notion that everyone likes white-spacey, airy apps that feel like contemporary products from successful start-ups, and that whitespace is not the only solution to structure content, or make things more efficient and still avoiding eyesore.

Key take away is

“ […] our users don’t have a choice, they have to use the tools we design—if they don’t think a system is usable, they can’t decide to just go download a different one. So we owe it to them to put their daily productivity first—always.”

2. The USSR computer of the future, that never was

This article on inexhibit https://www.inexhibit.com/case-studies/project-sphinx-when-the-ussr-tried-to-change-the-computer/ shows an interesting approach from the USSR of the late 80s to design a computer of the future, for the people. How bold was the move?

“The system was intended to replace all the technological devices in a house, computers, telephone, television, radio, audio system, and so on. To do that, a number of peripherals were included.”

It is basically a communist apple ecosystem of the 1980s, with the idea of a multiuser system in hardware.

For a continued reading on a more general topic, this article about “visionary computers of the past” gives you more interesting stuff to indulge and think about.

3. AR experience in a sports arena

https://twitter.com/sergcio/status/1171071776350253062/video/1

While the experience is enormously cool (in my book), it raises the question of how “real” our memories or the “memories” we share will actually be in the future.

4. You need data to build data driven products, and that’s the hard part

The article The death of a startup gives an insight about the best ideas not surviving reality because of a small, but existential flaw.

“Without training data, there was no ML model. There was no AI. Without the model, there was no solution. Without the solution, no company.”

It is short, but gives you again a quick summary of how to plan a product or “what to do instead”. Most valuable sentence is probably this, at least if you want or need your idea / product / company to earn money:

“Deliver value versus trying to push through your vision of a perfect world. Live to fight another day.”

5. Object Oriented UX

In conjunction with the tweet linked above goes this article about Object Oriented UX. It is from 2015, but I find it not the less valid.

“That’s OOUX: putting object design before procedural action design, and thinking about a system through the lens of the real-world objects in a user’s mental model (products, tutorials, locations), not digital-world actions (search, filter, compare, check out). We determine the actions after first defining the objects, as opposed to the traditional actions-first process that jumps straight into flows, interactions, and features.”

This approach is something that might be adapted more easily by “technical people” than by “visual people”, but I think it’s worth to at least try to view the thing you’re trying to build through this lens. It will most likely also reduce friction when it goes into implementation, as missing things are uncovered early and a way of organizing internal data can be easily derived from this.

6. e-commerce sites lack (the right) filters, and users don’t like that

Filters on e-commerce sites help users narrow down the abundance of choice and find what they’re actually looking for. Key is to always have the attributes that are shown on the product available as filters, too – as this is what differentiates the products. The lack of those often causes frustration and abandonment, as this article of Baymard Institute shows – up to 38%.

Linked from this page is the UX Benchmark, which is almost worth an entry of its own.

7. Mixed

• CSS Grid: Magazine Layout
• Blurry Web Spiders (WebGL)

Misc

Also, I have stumbled across Svelte, and I really like their concepts explained in this article / video “Rethinking Reactivity”. I hope I’ll find the time to dip my toes into it.

The new Ulysses feature really adds so much value to my “ideal blogging setup” that I hope to actually start writing more again.

A few years ago, I got started with editing in Markdown or a flavour thereof. Once you go there, it’s hard getting back to anything else. I still have a problem with writing Word Documents. Markdown is not perfect, but it helps me a lot writing structured documents and being quite fast in that. A little sideway to reStructuredText (IT! IS! ONE! WORD!) ended in tears, and I will hate making tables forever.

I’m using Ulysses, although I have also tried iA Writer and found this not too bad. But as I’ve had a beer or two with some of the good people behind Ulysses and I really like their attitude towards their product, and their general work ethics, I shifted and (almost) never looked back.

In the beginning I struggled with the application contained library (I like my files), and I wanted Dropbox support, as I did not trust Apple with anything that has to do with networks, leave alone syncing. I still find it a little odd to have links being represented in non-clear text, and images to be inline, but I do appreciate the beauty of it – and I constantly confuse that syntax anyway.

Around the same time, I discovered Ghost as a beautiful and very promising blogging solution, opposed to the then-already starting to bloat Wordpress. It looked minimalistic, yet thought through. There was also some promise in the admin panel that I haven’t seen yet but hey: aim high.

I’ve installed Ghost in version 0.3.1 as a test, and loved it. Although I rarely had time to write – or something to write about, but I duly installed the updates and saw what changed. I even had a Medium theme installed once… The writing experience was straightforward but beautiful. I’m still not sure how I feel about the blocks, but again: it makes life so much easier for non-technical users. And those who are can always add functionality.

Ghost lacked an API for a long time, and probably for a good reason – and I still ended up copying and pasting things from Ulysses, if I couldn’t export them as PDFs or needed them in the web. Not so much in this publication, as the posting frequency is rather low.

But yet, all of the time, I’ve had the “ideal setup” in mind. A clean web interface, text based articles formatted in markdown, and something that enables me to easily post “on the go” without logging in, uploading images etc pp. But also not a native app of the publishing platform, as these tend to suck at some point.

When I read the news about Ulysses integrating with Ghost, it seemed like I finally found what I was looking for. Now it’s time to take this for a spin, and produce the first content with it. I’m looking forward for more to come, and this time more frequently than yearly.

I've tried Ghost almost as soon as it came out. I liked the simplicity and writing in Markdown. Things changed, and you could see the inspiration from other publishing platforms. However, one thing was always annoying me: images.

When uploading an image to ghost, it would be sent the same way as it was uploaded. This means that images straight from the camera would be delivered to the reader in all its Megapixel beauty. For "mature CMS" or publishing platforms there would be a way to resize them for delivery, or at least compress them. This almost always required using GDlib or imagemagick and maintaining an additional component. Or your own asset server.

For Ghost there was no such option, and for a long time also no API to plug into for this. This GitHub issue speaks for itself and is a good documentation for the situation.

Things have changed, and with the release of Ghost 2.1 images are being resized. Finally! This was what was missing, and I hope the team will put this forward. I'll insert some images to demonstrate this.

Additionally, a "Gallery" block has been introduced, so let's see how useful this is.

This is a promising start. I don't know if there is a way to sort images, but one of the biggest needs has been addressed and I think Ghost is even more usable right now.

The images look quite compressed when viewed 1:1, but are astonishingly small in size. The gallery images cannot be clicked and zoomed, but that's more a theme thing. This page weighs 2.1MB, which is half of the size that any of these images had before the upload. There are no alt attributes possible.

However, when you insert a markdown block, you can still insert images "the old way". Which means, you could actually use an alt attribute.

The image will be treated the same way (longest side 2000px, hard compressed). I have uploaded the image above with an original size of almost 6MB.

So, happy publishing images!

A time to rethink. To recreate, to re-create. A time to rebuild. Or build new.

The time is now
(Moloko)

No worries, that is just a test post with the new theme. However, exciting things ahead. Also, almost a year has passed and it's time to publish another article, in the true tradition of this here publication.