DEV Community: Estela Franco

Create a Blog with Eleventy and Storyblok

Estela Franco — Mon, 13 May 2024 14:01:45 +0000

This is the third post in a series of articles called "Eleventy and Storyblok" to learn how to use this combination to create a web project.

TL;DR: Too much text for you? Don't worry! You have all the code described in this tutorial in this template repository: https://github.com/guaca/11ty-storyblok-template/. Keep in mind, however, that you will need to create your .env file with the proper variables described in this article for the template to work.

Now that you're familiar with why Eleventy + Storyblok is my ideal combination and how to seamlessly query data from Storyblok for use in an Eleventy project, it's time for the next exciting step: let's embark on creating a complete blog site using these two phenomenal technologies!

Creating the Blog Architecture in Storyblok

The desired blog content architecture has the following levels:

├── Homepage
├── articles
│   └── article-1
│   └── article-2
│   └── article-n
├── categories
│   └── category-1
│   └── category-2
│   └── category-n
└── authors
    └── author-1
    └── author-2
    └── author-n

So first you need to create a new site in Storyblok (you already learned how to do this in my previous article). Got it? Then let's create the data architecture and some initial content in it!

Removing the boilerplate content

Remove the default content that Storyblok adds when you create a new site. We will create the blocks and stories we need from scratch.

Creating the initial Blocks: Author and Category

Let's start by creating the Author type. To do this, go to the Block Library (which should be empty if you have deleted all the default blocks) tab and create a new block named Author. Select the option Content type block.

Let's edit it and define the required fields:

Name (text)
Bio (textarea)
Avatar (asset - images)

Remember to mark them as Required field if they are mandatory.

Let's repeat the process to create the Category type. Still in the Block Library, create a new Content type block type. In this case, the name is Category.

In this case, and to keep it simple for this tutorial, I have only defined one field called (surprise) Category.

Creating the first stories: Authors and Categories

Now that we have created two content types, let's create the first stories! To do that, go to the Content section (which should be empty) and create a new Folder.

Let's start with the Authors! During the definition of the folder, restrict the content type to Author. I also recommend you to check the Disable visual editor (Form only) as we won't use the visual editor in this tutorial.

You're now inside the (empty) Authors folder. Create a new Story. The pop-up will ask you for some basic data:

Name (required). Let's create the Author 1.
Slug (it's generated based on the name).
Parent folder. In this case, the Authors folder is the parent folder.
Content type (required). Select Author.

In the next screen, you will see the form with the fields that we defined when creating the Author type. Fill them and hit Save.

You can repeat the process and create some more authors. In my case, I have created another one, called (surprise) Author 2.

Let's now move on and create some Categories. You can repeat the process and create the Categories folder, which should be restricted to the Category content type. Remember to check the Disable visual editor (Form only) checkbox as we're not using this feature in this tutorial.

Now that you're inside the Categories folder, create a new story. In this case, it also asks you for some basic information:

Name (required). For this example, I'm super creative and I have created the Category One.
Slug (it's generated from the name).
Parent folder: Categories.
Content type: Select Category.
In the next screen, you will see the category form asking for the Category. In this basic example, this field is also Category One.

And what about the Articles?

Yes, I know. This is supposed to be a blog site, but I haven't covered the articles yet, right? That's because we're going step by step. And this is the step to start creating Articles.

Let's start by creating the Article content type. Remember how to do this? Correct! Go to the Block Library and create a new Block.

Technical name: Article.
Select block type: Content type block. And press Add Block.

Now edit it to add the fields.

Title: Text.
PublicationDate: Date/Time.
Author. And that's why we created the authors first! Choose the Single-Option type and choose the following source details:
- Source: stories
- Path to the folder of stories: authors/
- Restrict to content type: Author
Category. Similar to what we have done for Author. It is also a Single-Option type and these are the source details:
- Source: stories
- Path to the folder of stories: categories/
- Restrict to content type: Category
Body. Select Markdown, but check the Rich-text as default checkbox. This will allow you to have a WYSIWYG interface, but it will be saved (and served) as Markdown. As I mentioned in the first article of this series, Markdown is one of the template languages that you can use in your project. Therefore, choosing Markdown will be easier to manage than using the Richtext option.

And you already have the Article block created!

Let's now create the first article. Go to the Content section and create a new Folder called Articles:

Name: Articles.
Slug (it's generated from the Name).
Parent folder: Root.
Content type: Restrict content types to Articles

Once again, remember to disable the visual editor (Form only).

And now you will see the form to create your first article. You've seen that I am being very creative with the content I'm using in this new blog site, so you won't be surprised by my first article:

As you can see, the Author and Category were selected from the drop-down list.

You can repeat these steps to generate a few more articles. I have created a total of 3 articles for this tutorial.

Creating a Homepage

Last but not least, we need a homepage for our brand new blog site. You've seen how creative I've been with the rest of the content. So, the homepage can't be any different!

Let's create the Block first. As usual, go to the Block library and create a new one with the following information:

Technical name: Page (I used this, but feel free to use whatever works better for you).
Select block type: Content type block.

And now, let's define the fields:

Heading: Text.
Subtitle: Text.
Highlights: Multi-Options
- Source: Stories
- Path to folder of stories: articles/
- Restrict to content type: Article
- Minimum: 3
- Maximum: 5

So, our homepage will have a heading, a subtitle and a list of the top articles.

Let's now create the homepage content. Go to Content, create a new Story and the pop-up will ask you for some basic information:

Name (required)
Slug (it's generated from the name)
Parent folder: Root
Content type: Page

On the next screen, you will see the visual editor enabled. This is happening because Storyblok does offer to disable the visual editor when creating a Folder, but not when creating a Story. Let's disable it as we're not going to use it in this tutorial.

To do it, access the Entry configuration from the navbar above the visual editor. This will open a pop-up and you will see the Edit mode options. Check the Form-only one.

Ok, it looks easier this way, right? Let's fill the fields with my already-famous creative content:

Heading: This is the Homepage
Subtitle: Welcome to the homepage of this amazing web site!
Highlights: In my example, I created 3 articles and I will select them all. An important detail: it's a reordable drag-and-drop list, so feel free to sort them however you like.

And that's it! You have your headless CMS created and ready to generate new content.

Wait. And what about SEO?

If this question has crossed your mind, THANK YOU! Because we need more people who care about making our sites "SEO friendly" since the first stage of the project.

And if you haven't thought about it, don't worry. I'm here to add this topic just in time.

Create the SEO block

Let's go to the Block Library and create a new nestable block. Call it SEO. Define a minimum and maximum of 1 block.

Add the following fields:

title: text.
description: text.
canonical: text.
noindex: boolean. The default value will be disabled.
og_title: text.
og_description: text.
og_image: asset (image).

Add the SEO block to the other blocks

We want to be able to define the proper SEO and Social Media data for all the stories we have already created, so we need to add it to the related content types:

Article
Author
Category
Page

Once you've added the SEO block to them, you can access the content and add the SEO data:

Creating the Eleventy project

Alright, you've got the content, but now it's time to build the site that will put that content to use, right? The following steps will help you achieve the desired project structure:

├── src
│   └── _data
│   │    └── articles.js
│   │    └── authors.js
│   │    └── categories.js
│   │    └── home.js
│   │    └── metadata.json
│   └── includes
│   │    └── layouts
│   │    │    └── base.njk
│   │    └── footer.njk
│   │    └── head.njk
│   │    └── header.njk
│   └── public
│   │   └── css
│   │       └── styles.css
│   └── utils
│   │   └── storyblok.js
│   └── article-page.njk
│   └── articles-list.njk
│   └── author-page.njk
│   └── authors-list.njk
│   └── category-page.njk
│   └── categories-list.njk
│   └── index.njk
└── eleventy.js
└── .env
└── .gitignore
└── package.json

Setting up and configuring the Eleventy project

You already learned how to do this in my previous article, so I'll make it faster this time.

1. Create and access your project (and open it using VSCode)

 mkdir myproject
 cd myproject
 code .

2. Create your `package.json` file in the root directory and paste the following lines:

{
 "scripts": {
   "build": "npx @11ty/eleventy",
   "start": "npx @11ty/eleventy --serve"
 },
 "devDependencies": {
   "@11ty/eleventy": "^2.0.1",
   "dotenv": "^16.4.1"
 }
}

3. Install dependencies

npm install

4. Create the `.env` file in the root directory

STORYBLOK_API_KEY="[your-storyblok-token-goes-here]"
DOMAIN="[your-website-domain-goes-here]"

5. Create the `eleventy.js` config file

require('dotenv').config()
module.exports = function (eleventyConfig) {
 // Add the .env domain as GlobalData to use in SEO meta data
 eleventyConfig.addGlobalData("domain", process.env.DOMAIN );

 // Filter articles by Author slug
 eleventyConfig.addFilter("filterArticlesByAuthor", function(articles, authorFullSlug) {
   const filteredArticles = articles.filter(article => {
     return article.content.Author.fullSlug === authorFullSlug;
   });
   // Sort the filtered articles by PublicationDate in descending order
   filteredArticles.sort((a, b) => {
     return new Date(b.content.PublicationDate) - new Date(a.content.PublicationDate);
   });
   return filteredArticles;
 });

 // Filter articles by Category slug
 eleventyConfig.addFilter("filterArticlesByCategory", function(articles, categoryFullSlug) {
   const filteredArticles = articles.filter(article => {
     return article.content.Category.fullSlug === categoryFullSlug;
   });
   // Sort the filtered articles by PublicationDate in descending order
   filteredArticles.sort((a, b) => {
     return new Date(b.content.PublicationDate) - new Date(a.content.PublicationDate);
   });
   return filteredArticles;
 });

 // Sort the authors  by name: 
 eleventyConfig.addFilter("sortAuthorsByName", function(authors) {
   return authors.sort((a, b) => a.content.Name.localeCompare(b.content.Name));
 });

 // Pass Trhough Copy
 eleventyConfig.addPassthroughCopy({
   "./src/public/": "/",
 });

 return {
   dir: {
     input: 'src'
   },
 };
};

What have we done here? Let's go one by one:

Initializing dotenv
This initial line populates env variables into process.env and makes it available in the config file.
Add Global Data
We're adding the DOMAIN enviroment variable as Global Data, ensuring it's available throughout the project.
Filter articles by Author
We've defined a new filter to retrieve articles authored by a specific author. This filter will be applied on the Author's page to list all articles authored by that individual. Additionally, the articles will be sorted by PublicationDate in descending order.
Filter articles by Category
Similar to the previous filter, here we're filtering articles belonging to a specific Category. This filter will be utilized on the Category's page to list all articles within that particular Category. Once again, the articles are sorted by PublicationDate in descending order.
Sort authors by name
This filter enables us to arrange the list of authors alphabetically by their names.

6. Create the `src > _data > metadata.json` file

{
   "title": "My site",
   "language": "en",
   "description": "Welcome to my blog site!",
   "image": "[fallback-image-for-social-media-goes-here]"
}

7. Create the `src > _includes > head.njk` file

<head>
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>{{ title or metadata.title }}</title>
 <link rel="stylesheet" href="/css/styles.css">
 <meta name="description" content="{{ description or metadata.description }}">
 <link rel="canonical" href="{{ canonical or domain+page.url }}">
 {% if noindex == "true" %}
   <meta name="robots" content="noindex">
 {% endif %}
 <meta property="og:title" content="{{ og_title or title or metadata.title }}">
 <meta property="og:description" content="{{ og_description or description or metadata.description }}">
 <meta property="og:image" content="{{ og_image or metadata.image }}">
 <meta name="twitter:card" content="summary_large_image">
 <meta name="twitter:title" content="{{ og_title or title or metadata.title }}">
 <meta name="twitter:image" content="{{ og_image or metadata.image }}">
</head>

This might seem a bit overwhelming, right? It's because we're integrating Nunjucks variables and conditionals (using curly braces) with HTML tags. However, it's just as straightforward and incredible as you saw in the previous code.

For example <link rel="canonical" href="{{ canonical or domain+page.url }}"> generates a canonical link with the canonical URL sourced from the frontmatter data. If that's missing, it constructs a canonical URL by combining the domain (Global Data) with the URL of the current page. BOOM!

8. Create the `src > _includes > header.njk` file

<header>
 <nav class="header-nav">
   <a class="header-home" href="/">My site</a>
   <ul class="header-list">
       <li class="header-item"><a href="/articles/">Articles</a></li>
       <li class="header-item"><a href="/authors/">Authors</a></li>
       <li class="header-item"><a href="/categories/">Categories</a></li>
   </ul>
 </nav>
</header>

9. Create the `src > _includes > footer.njk` file

 <footer>
   © 2024 - All Rights Reserved
 </footer>

10. Create the `src > _includes > layouts > base.njk` file

<!DOCTYPE html>
<html lang="{{ metadata.language }}">
{% include "head.njk" %}
<body>
 {% include "header.njk" %}
 <main style="flex-grow:1;">
   {{ content | safe }}
 </main>
 {% include "footer.njk" %}
</body>
</html>

That seemed a bit weird, didn't it? Let's break it down step by step.

The lang attribute in the HTML comes from the metadata.json file, where we've set the language.
We utilize include to pull in the templates we've created (head, header and footer).

11. Create the `src > utils > storyblok.js` file

require('dotenv').config()
module.exports = async function fetchAPI(query, { variables, preview } = {}) {
   const res = await fetch("https://gapi.storyblok.com/v1/api", {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
       Token: process.env.STORYBLOK_TOKEN,
       Version: "published",
     },
     body: JSON.stringify({
       query,
       variables,
     }),
   });

   const json = await res.json();
   if (json.errors) {
     console.error(json.errors);
     throw new Error("Failed to fetch API");
   }
   console.log(json.data)
   return json.data;
 }

This code may sound familiar because we've already covered it in the previous article. Remember, I'm using the published version, but you might opt for the draft version if this template isn't intended for a production site.

12. Create your `src > _data > articles.js` file.

It will generate the global articles data file, which you'll utilize to create your article pages. This is the code for this file:

const fetchAPI = require("../utils/storyblok.js");


module.exports = async function getArticles () {
 const data = await fetchAPI(`
 {
   ArticleItems {
     items {
       full_slug
       content {
         Body
         PublicationDate
         Title
         Author {
           name
           fullSlug
         }
         Category {
           name
           fullSlug
         }
         SEO
       }
     }
   }
 }  
 `);
 return data?.ArticleItems.items;
}

13. Create the `src > article-pages.njk` file

---
pagination:
   data: articles
   size: 1
   alias: article
permalink: "{{ article.full_slug }}/"
layout: layouts/base.njk
templateEngineOverride: njk,md
eleventyComputed: 
   title: "{{ article.content.SEO[0].title }}"
   description: "{{ article.content.SEO[0].description }}"
   canonical: "{{ article.content.SEO[0].canonical }}"
   noindex: "{{ article.content.SEO[0].noindex }}"
   og_title: "{{ article.content.SEO[0].og_title }}"
   og_description: "{{ article.content.SEO[0].og_description }}"
   og_image: "{{ article.content.SEO[0].og_image.filename }}"
---
<article>
   <h1>{{ article.content.Title }}</h1>
   <a href="/{{ article.content.Author.fullSlug }}">{{ article.content.Author.name }}</a>
   <span> - </span>
   <a href="/{{ article.content.Category.fullSlug }}">{{ article.content.Category.name }}</a>
   <p>{{ article.content.PublicationDate }}</p>
   <div>
       {{ article.content.Body | safe }}
   </div>
</article>

Yes, that's a lot of SEO and Social Media metadata, but it's necessary! You might be wondering why this data is under eleventyComputed instead of being set directly, like we did with permalink.

And that's a great question! We can only use variables and shortcodes in permalink and eleventyComputed. Therefore, we don't need to set the permalink under eleventyComputed, but the rest of the custom fields must be placed there to ensure they are dynamicly updated."

14. Create the `src > articles-list.njk` file

This template will list all the published articles.

---
permalink: "/articles/"
layout: layouts/base.njk
title: "Articles"
description: "This is the list of Articles"
---
<div>
   <h1>Articles</h1>
   <ul>
       {% for article in articles %}
       <li><a href="/{{ article.full_slug }}">{{ article.content.Title }}</a></li>
       {% endfor %}
   </ul>
</div>

15. Repeat steps 12 through 14, but this time creating the files related to `Authors`

Filename: src > _data > authors.js

const fetchAPI = require("../utils/storyblok.js");

module.exports = async function getAuthors () {
 const data = await fetchAPI(`
 {
   AuthorItems {
     items {
       full_slug
       content {
         Name
         Bio
         Avatar {
           filename
         }
         SEO
       }
     }
   }
 }
 `);
 return data?.AuthorItems.items;
}

Filename: src > author-page.njk

---
pagination:
   data: authors
   size: 1
   alias: author
permalink: "{{ author.full_slug }}/"
layout: layouts/base.njk
eleventyComputed: 
   title: "{{ author.content.SEO[0].title }}"
   description: "{{ author.content.SEO[0].description }}"
   canonical: "{{ author.content.SEO[0].canonical }}"
   noindex: "{{ author.content.SEO[0].noindex }}"
   og_title: "{{ author.content.SEO[0].og_title }}"
   og_description: "{{ author.content.SEO[0].og_description }}"
   og_image: "{{ author.content.SEO[0].og_image.filename }}"
---

<div>
   <div class="author-info">
       <img class="author-avatar" src="{{ author.content.Avatar.filename }}">
       <h1 class="author-name">{{ author.content.Name }}</h1>
   </div>
       <p>{{ author.content.Bio }}</p>
   <h2>Articles by {{ author.content.Name }}</h2>

   {% set targetAuthorFullSlug = author.full_slug %}
   {% set filteredArticles = articles | filterArticlesByAuthor(targetAuthorFullSlug) %}
   <ul>
       {% for article in filteredArticles %}
           <li>
               <article>
                   <h3><a href="/{{ article.full_slug }}">{{ article.content.Title }}</a></h3>
                   <span>Publication Date: {{ article.content.PublicationDate }}</span>
               </article>
           </li>
       {% else %}
           <p>No articles found for this author.</p>
       {% endfor %}
   </ul>

</div>

Filename: src > authors-list.njk

---
permalink: "/authors/"
layout: layouts/base.njk
title: "Authors"
description: "This is the list of Authors"
---
<div>
   <h1>Authors</h1>
   <ul>
       {% for author in authors | sortAuthorsByName %}
       <li><a href="/{{ author.full_slug }}">{{ author.content.Name }}</a></li>
       {% endfor %}
   </ul>
</div>

16. Repeat steps 12 through 14, but this time creating files related to `Categories`

Filename: src > _data > categories.js

const fetchAPI = require("../utils/storyblok.js");

module.exports = async function getCategories () {
 const data = await fetchAPI(`
 {
   CategoryItems {
     items {
       full_slug
       content {
         Category
         SEO
       }
     }
   }
 }
 `);
 return data?.CategoryItems.items;
}

Filename: src > category-page.njk

---
pagination:
   data: categories
   size: 1
   alias: category
permalink: "{{ category.full_slug }}/"
layout: layouts/base.njk
eleventyComputed: 
   title: "{{ category.content.SEO[0].title }}"
   description: "{{ category.content.SEO[0].description }}"
   canonical: "{{ category.content.SEO[0].canonical }}"
   noindex: "{{ category.content.SEO[0].noindex }}"
   og_title: "{{ category.content.SEO[0].og_title }}"
   og_description: "{{ category.content.SEO[0].og_description }}"
   og_image: "{{ category.content.SEO[0].og_image.filename }}"
---
<div>
   <h1>{{ category.content.Category }}</h1>

   {% set targetCategoryFullSlug = category.full_slug %}
   {% set filteredArticles = articles | filterArticlesByCategory(targetCategoryFullSlug) %}
   <ul>
       {% for article in filteredArticles %}
           <li>
               <article>
                   <h3><a href="/{{ article.full_slug }}">{{ article.content.Title }}</a></h3>
                   <span>Publication Date: {{ article.content.PublicationDate }}</span>
               </article>
           </li>
       {% else %}
           <p>No articles found for the author with Full Slug "{{ targetAuthorFullSlug }}".</p>
       {% endfor %}
   </ul>
</div>

Filename: src > categories-list.njk

---
permalink: "/categories/"
layout: layouts/base.njk
title: "Categories"
description: "This is the list of Categories"
---
<div>
   <h1>Categories</h1>
   <ul>
       {% for category in categories %}
       <li><a href="/{{ category.full_slug }}">{{ category.content.Category }}</a></li>
       {% endfor %}
   </ul>
</div>

17. Create the `Home` related files

In this case, we need the Home id. You can find it using the GAPI browser, as I explained in my previous article.

Once you have the home id, add the variable in the .env file:

  STORYBLOK_API_KEY="[your-storyblok-token-goes-here]"
  DOMAIN="[your-website-domain-goes-here]"
  HOME_ID="[your-home-id]"

Create the src > _data > home.js file and add the following code in it:

require('dotenv').config()
const fetchAPI = require("../utils/storyblok");

module.exports = async function getHome () {
 const data = await fetchAPI(`
 {
   PageItem(id: "${process.env.HOME_ID}") {
     content {
       Heading
       Subtitle
       Highlights {
         fullSlug
         name
         content
       }
       SEO
     }
   }
 }  
 `);
 return data?.PageItem;
}

Create the src > index.njk file:

---
pagination:
   data: home
   size: 1
permalink: "/"
layout: layouts/base.njk
eleventyComputed: 
   title: "{{ home.content.SEO[0].title }}"
   description: "{{ home.content.SEO[0].description }}"
   canonical: "{{ home.content.SEO[0].canonical }}"
   noindex: "{{ home.content.SEO[0].noindex }}"
   og_title: "{{ home.content.SEO[0].og_title }}"
   og_description: "{{ home.content.SEO[0].og_description }}"
   og_image: "{{ home.content.SEO[0].og_image.filename }}"
---
<h1>{{ home.content.Heading }}</h1>
<p class="home-subtitle">{{ home.content.Subtitle }}</p>

<h2>Highlighted Articles</h2>
<ul>
   {% for article in home.content.Highlights %}
   <li><a href={{ article.fullSlug }}>{{ article.content.Title }}</a></li>
   {% endfor %}
</ul>

18. Create the `src > public > css > styles.css` file

/* Colors */
:root {
   --darkgray: #202124;
   --purple: #713973;
   --white: #FFF;
}
body {
 background-color: var(--white);
 color: var(--darkgray);
 display: flex;
 flex-direction: column;  
 font-family: system,-apple-system,system-ui,BlinkMacSystemFont,Roboto-Light,sans-serif;
 font-size: clamp(1.1em, calc(0.25vw + 0.8em), 1.25em);
 margin: 0;
 min-height: 100vh;
 padding: 0;
}
header {
 display: flex;
 justify-content: space-between;
 border-bottom: 1px solid var(--darkgray);
}
footer {
 border-top: 1px solid var(--darkgray);
 text-align: center;
 padding: 1em;
}
main {
 flex-grow: 1;
 margin: 4em auto 0 auto;
 width: min(60em, 90%);
}
.header-home {
 text-decoration: none;
 font-size: 1.5em;
 font-weight: 600;
 color: var(--darkgray);
 &:hover {
     color: var(--purple);
 }
}
.header-nav {
 display: flex;
 align-items: center;
 width: min(60em, 90%);
 margin: 0 auto;
}
.header-list {
 margin-right: 1em;
 padding: 0;
 list-style: none;
 float: left;
 margin-left: 1em;
 display: flex;
 justify-content: flex-end;
 flex-grow: 1;
 list-style: none;
}
.header-item {
 font-size: 1em;
 & a {
     margin: 0 1em;
     color: var(--darkgray);
     text-decoration: none;
     &:hover {
         color: var(--purple);
     }
 }
}
.author-avatar {
   width: 75px;
}
.author-name {
   margin-left: 1.5em;
}
.author-info {
   display: flex;
   flex-direction: row;
}
p:empty {
 display: none;
}

Run it locally

You're nearly finished! With your content in Storyblok and your code stored in a local repository, it's time to run it locally and ensure everything appears as intended.

npm start

Executing this command will run Eleventy locally, making your brand new (local) site accessible at port 8080. If port 8080 is already in use, the correct port will be displayed in the console.

Demo and Template Repository

You can see this blog site in action here: https://11ty-storyblok.netlify.app

In addition, you have all the code described in this tutorial in this template repository: https://github.com/guaca/11ty-storyblok-template/. So, you can create your own blog site by clicking the "Use this template" button.

What's next?

This tutorial has guided you through configuring and building a blog site, utilizing Storyblok for data storage and Eleventy for page generation. Once completed, you can deploy your Eleventy project to your preferred Jamstack hosting service. By setting up appropriate workflows and hooks, you can ensure that your site updates automatically whenever you publish a new story in Storyblok.

You have all these steps defined in this article.

Can I use the Storyblok Visual Editor with Eleventy?

Long answer short? Yes but it's not straightforward.

Long answer: Yes, you can leverage it by configuring an edge function to refresh the API/GAPI data from Storyblok upon updates. Eleventy generates data during build time. Consequently, even after saving new data, the data won't be updated in the Visual Editor preview unless the edge function rebuilds it.

Storyblok's visual editor seamlessly integrates with other frameworks like Next or Nuxt, allowing you to observe content updates instantly, even without saving changes. However, this functionality is not supported by static site generators.

In the next article in this series, I will use Netlify Edge functions to leverage the Storyblok Visual Editor to make working with the editor easier and more intuitive. Stay tuned!

How to connect Eleventy and Storyblok

Estela Franco — Sat, 10 Feb 2024 21:49:09 +0000

This is the second post in a series of articles called “Eleventy and Storyblok” to learn how to use this combination to create a web project.

Before getting into the matter, I really recommend you to read my first article of this series if you haven’t yet. Take a moment to check it out and discover why Evleventy and Storyblok is my perfect combination and why you should start using it to take advantage of these two technologies. You can read i here.

So, in this second article, I explain to you how to connect Eleventy and Storyblok to start consuming content generated in this amazing Headless CMS.

Technical requirements

This article will show you step by step how to query data from Storyblok to use it in an Eleventy project. You'll need a computer with the following features:

Node.js. Eleventy requires Node.js 14. I've used v20.10.0 in the examples provided.
- You can check if you have Node installed by running node --version in a terminal window.
- If the command is not found or returns a number less than 14, you will need to download and install Node.js before proceeding to the next step.
A code editor. I use VSCode, but feel free to use your favorite.
A Storyblok account. You can create yours here.
Basic knowledge of HTML, CSS, JavaScript, Markdown, and the command line is helpful.

Once you have all the technical requirements in place, it's time to create the project.

Creating a project in Storyblok

First of all, let's create a basic Storyblok space for this project!

Select the New Space option, enter a name for the space, and select the server location (EU by default):

You can review the structure and sample content details. By default, you'll find the following components:

A Home page in the Content section:

When you access it, you will see the "Welcome to the Visual Editor" page by default, and the components of the page in the right sidebar:

As you can see, the Home page has a body component with two block elements:

Teaser: this is a text component. The current value of this field is "Hello world!".

Grid: this is a block component, with 3 text elements in it (with the text "Feature 1", "Feature 2", and "Feature 3" text on them).

We'll cover this later, but understanding the architecture of data is key to creating the right elements in your front-end development.

Creating a project in Eleventy

Eleventy does not require you to use any JavaScript framework or library. And you can have a basic project up and running in literally less than 1 minute:

Open a terminal
Create a folder for your new project

mkdir myproject

Access the project

cd myproject

Create an index.md file. The .md extension is for markdown.

echo '# Page header' > index.md

Run Eleventy. This command compiles the index.md file (but .md is only one of many valid file extensions) into the output folder(_site by default), ready to be upload to your favorite hosting service.

npx @11ty/eleventy

You should get something like this:

[11ty] Writing _site/index.html from ./index.md (liquid)
[11ty] Wrote 1 file in 0.03 seconds (v2.0.1)

However, you may want to run Eleventy from a local development server while working on it. Run Eleventy locally with this code:

npx @11ty/eleventy --serve

You will get something like this:

[11ty] Writing _site/index.html from ./index.md (liquid)
[11ty] Wrote 1 file in 0.04 seconds (v2.0.1)
[11ty] Watching…
[11ty] Server at http://localhost:8080/

Open http://localhost:8080 in your browser and you will see your website.

Setting up and configuring the Eleventy project

So far, so simple, right? Your project should have the following architecture:

├── _site
│   └── index.html
└── index.md

But let's add a few more things to prepare our project for our Storyblok integration.

We've created our first page, index.html, using one of the valid file extensions (.md). But this is just one of many options you can use for your templates:

HTML: *.html
Markdown: *.md
WebC: *.webc
JavaScript: *.11ty.js
Liquid: *.liquid
Nunjucks: *.njk
Handlebars: *.hbs
Mustache: *.mustache
EJS: *.ejs
Haml: *.haml
Pug: *.pug
Custom: *.*

I will use .md and .njk in this article, but feel free to use the template languages you feel more comfortable with.

There's plenty of options to use, combine and override the template language. You can find all the details in the documentation.

In addition to pages, you can use layouts to wrap other content. So let's open the project in VSCode and let's create a base layout to define the common HTML elements for all pages:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>{{ "{{ title }}" }}</title>
  </head>
  <body>
    {{ "{{ content | safe }}"}}
  </body>
</html>

Save this file as base.njk in a new _includes/layouts folder. Your project now has the following structure:

├── _includes
│   └── layouts
│       └── base.njk
├── _site
│   └── index.html
└── index.md

Now you can add the base.njk layout to your index.md page. To do this, add the following information to your existing file

+ ---
+ layout: layouts/base.njk
+ title: "This is my homepage"
+ ---

# Page header

What have been done here? The content between the two --- marks is the front matter. This is a YAML block at the top of the file and is a standard convention used by many Static Site Generators (SSG). So you're probably familiar with it if you've used other SSGs in the past. The content in the front matter is key-value pairs that provide information on how to generate data for this page.

In this case, two key-value pairs have been added:

layout: This is the route of the desired layout to apply to the page.
title: This is the title of the page. As mentioned earlier in the base.njk file, this information will be used in the <title> tag.

Get the API token from Storyblok

An API token is necessary to follow the next steps. By default, you can see your preview token on the "Welcome to the Visual Editor" page. But you can find it (or create a new one) in Settings > Access Tokens as well.

How to query the Storyblok data from Eleventy

Create the GraphQL query

In this article, I will be using the GraphQL Content Delivery API. This is is a read-only endpoint and is optimized for fast content delivery.

Use the following endpoint to send GraphQL requests:

https://gapi.storyblok.com/v1/api

Note that you need to append the region code if you are using different regions. For example:

https://gapi-us.storyblok.com/v1/api

If you haven't used GraphQL schemas before, I have good news for you! Storyblok has a playground where you can explore the functionalities and create the right query. You can access it using this URL with your Access Token in it:

https://gapi-browser.storyblok.com/?token=insert-here-your-access-token

In this case, we want to get the Home page data:

Teaser (Hello world!)
Grid
- Feature 1
- Feature 2
- Feature 3

So, this will be our query:

{
  PageItem(id: "insert-your-home-id") {
    name
    content {
      body
    }
  }
}

You can find your Home id running the following query in the playground:

{
  PageItems {
    items {
      id
      name
    }
  }
}

And it will return the id and the name:

{
  "data": {
    "PageItems": {
      "items": [
        {
          "id": xxxxxxxxxx,
          "name": "Home"
        }
      ]
    }
  }
}

Ok, now we know what data we want to get from Storyblok. But how to do it?

Data in Eleventy

Eleventy can use data from several different sources. However, when merging data, there is a priority order for data sources. From highest to lowest priority:

Computed data
Front matter data in a template
Template data files
Directory data files
Front matter data in layouts
Configuration API global data
Global data files

The two ways that work best for applying a headless CMS are Global Data files and Configuration API global data. In this article, I'm going to use the first one.

As you can imagine, this means some code is necessary to execute the API call. Let's create a folder called utils. Inside it, create a storyblok.js file with the following code:

module.exports = async function fetchAPI(query, { variables, preview } = {}) {
    const res = await fetch("https://gapi.storyblok.com/v1/api", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        Token: "xxxxxxxxxxxxxxxxxxxxxxxx",
        Version: preview ? "draft" : "published",
      },
      body: JSON.stringify({
        query,
        variables,
      }),
    });

    const json = await res.json();
    if (json.errors) {
      console.error(json.errors);
      throw new Error("Failed to fetch API");
    }
    console.log(json.data)
    return json.data;
  }

Hardcoding your API token into your code is not a good practice. So you can store it as an .env variable.

# .env file
STORYBLOK_TOKEN: xxxxxxxxxxxxxxxxxxxxxxxx

However, you will need to install the dotenv package to access it.

npm install dotenv --save-dev

You will see this step will generate some more files and folders. Don't worry, we'll manage this later. Now you can modify your storyblok.js file to use the .env variable:

+ require('dotenv').config()
module.exports = async function fetchAPI(query, { variables, preview } = {}) {
    const res = await fetch("https://gapi.storyblok.com/v1/api", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
-        Token: "xxxxxxxxxxxxxxxxxxxxxxxx",
+        Token: process.env.STORYBLOK_TOKEN,
        Version: preview ? "draft" : "published",
      },
      body: JSON.stringify({
        query,
        variables,
      }),
    });

    const json = await res.json();
    if (json.errors) {
      console.error(json.errors);
      throw new Error("Failed to fetch API");
    }
    console.log(json.data)
    return json.data;
  }

At this point, let's create a _data folder, and a homepage.js file in it with the following code:

const fetchAPI = require("../utils/storyblok");

module.exports = async function getHomepage () {
  const data = await fetchAPI(`
  {
    PageItem(id: "insert-your-home-id") {
      name
      content {
        body
      }
    }
  }
  `);
  return data?.PageItem;
}

The previous code will generate the homepage data from Storyblok's API, and it will be accessible from other pages and layouts.

So let's modify our index.md file to use it!

---
layout: layouts/base.njk
title: This is my homepage
---

- # Page header
+ {{ "{{ homepage.content.body[0].headline }}" }}
+ {{ "{{ homepage.content.body[1].columns[0].name }}" }}
+ {{ "{{ homepage.content.body[1].columns[1].name }}" }}
+ {{ "{{ homepage.content.body[1].columns[2].name }}" }}

After following all these steps, you should see something similar to this on your local server:

Using the Visual Editor from Storyblok

As seen earlier, the Visual Editor uses a "Welcome to the Visual Editor" by default page. To see the page we've created using Storyblok's data we must set up the preview URL. Eleventy runs locally on http://localhost:8080. However, Storyblok requires an https connection to use the visual editor. There are several frameworks offering straightforward methods to use SSL in local development. Unfortunately, it's not that easy on Eleventy.

However, we can fis this issue with mkcert and local-ssl-proxy. Before following this process, ensure your local server is stopped. If it's still running, you can stop it by clicking Control + C.

Install mkcert (globally)

npm install -g mkcert

Add mkcert to your local root CAs

mkcert -install

Generate a certificate for your localhost on your project, signed by mkcert. This will generate two .pem files.

mkcert localhost

Install local-ssl-proxy (globally)

npm install -g local-ssl-proxy

Run Eleventy locally (and keep this terminal running it!). By default, it will run over the port 8080:

npx @11ty/eleventy --serve

Open a new terminal and run the proxy SSL server through the port 3000 (and keep it running in this new terminal):

local-ssl-proxy --source 3000 --target 8080 --cert localhost.pem --key localhost-key.pem

After these steps, open https://localhost:3000 on your browser and you should be able to see the same content as on http://localhost:8080.

With these two local servers running, you can go to Storyblok and change the preview URL. You can set it up directly from the default "Welcome to the Visual Editor" page, in the "Set up preview URL" field. Or you can change the preview URL from Settings > Configuration > Visual Editor:

But you will probably be a bit disappointed after doing this because you'll get a 404 error after saving it. That's because Storyblok adds the content page path to the URL. So, by default, the visual editor will try to load https://localhost:3000/home. To change this, go to the page configuration and set / as the Real path:

And now you have it! You can see the content using the Visual Editor.

Next steps

After following all these steps, you now know how to create content on Storyblok and consume it from Eleventy using the GraphQL API. However, you will notice that content management is not dynamic. If you change something in Storyblok, it will not be updated on the local server or in the visual editor.

That's the expected behavior because Eleventy executes the GraphQL query at build time. If we serve the page locally, this means that the query won't be updated unless we change a file in our project. Therefore, any changes we make won't be visible on Storyblok until we rebuild the project on our local server.

That's a bit annoying, isn't it? But don't worry. I will show you how to overcome all these inconveniences in my next article (part 3) of this series of Eleventy and Storyblok articles.

Eleventy and Storyblok — My perfect combination

Estela Franco — Mon, 09 Oct 2023 10:59:37 +0000

This is the first post in a series of articles called "Eleventy and Storyblok" to learn how to use this combination to create a web project.

If you know me, you already know that I'm a big Eleventy fan. So far, it's my favorite choice for creating a static project. But you can do so much more with it. You can even build an SPA with 11ty! The only downside to the escalation of my personal projects is the lack of a CMS to generate new content.

Don't get me wrong. I feel super comfortable writing in Markdown, but sometimes I miss the power of a CMS to easily check grammar mistakes or even preview the content instead of running my project on localhost.

That's why I started researching how to integrate a headless CMS into an Eleventy project. After investigating a few options, I fell in love with Storyblok.

In this article, I'll explain why I chose these options in the hope that you'll fall in love with them, too.

Eleventy, a simpler static site generator

11ty in a nutshell: Fast builds and even faster websites. That's what I'm looking for when starting a new project, so Eleventy seems to be made for my needs! But let the data speak for itself.

Eleventy ran a benchmark of x4000 Markdown files (you have all the information in this open source repository and the results in this article) and Eleventy performance is impressive:

Name	Building ×4000 MD Files
Eleventy	1.93s
Astro	22.90s
Gatsby	29.05s
Next.js	70.65s

Performance is important, but so is the developer experience. And I love the versatility of 11ty: you can create a project and choose between many template languages like HTML, Markdown, Nunjucks, Liquid, WebC, and others. You can even override the template language if you need to!

In addition, there are many official plugins that you can integrate into your project to take it to the next level easily. Or you can integrate plugins contributed by the community!

And that's important to me: Eleventy has an active community that helps make this SSG a great option.

For example, you can easily configure your templates using data keys like permalinks, layouts, pagination, tags, etc. And integrate plugins like Image (to resize and generate images), RSS, i18n (for internationalization), Navigation (also for breadcrumbs!), Shopify (import your Shopify products, pages and collections into Eleventy as global data), and more.

But don't take my word for it and see who trusts Eleventy to build their projects:

Storyblok, the way to modern content

As you can see, Eleventy is a super powerful SSG that provides a great DX. However, if your project has content editors creating articles and pages, they won't be as excited as developers. Creating content directly on an SSG project can be difficult until they know how to write using Markdown or other project options.

So implementing a headless CMS is a great solution to solve this problem. As I told you before, after investigating several options, I fell in love with Storyblok, and you will agree with me after reading this article.

But let's take a step back.

What's a headless CMS?

A headless CMS is a pure backend web content management system that acts as a content repository. The content is then exposed through an API for display on any device, without a built-in front-end. This separates your data (body) from its presentation (head).

Separating the two gives you remarkable freedom and allows you to integrate Storyblok into any project such as websites, ecommerces, or apps. Moreover, developers can use whatever technology they want without worrying about how it affects the front end, and content editors can reuse their content on any number of devices of any type because it's not tied to a specific channel.

Why Storyblok?

Storyblok is a headless CMS designed to empower all content stakeholders while providing a cloud-native, headless architecture that allows developers to effortlessly work with and adapt to any technology.

Here are some of its most notable features:

Headless: You can integrate Storyblok into any front-end project because it's a headless solution. Moreover, you can change your front-end and easily migrate your content from one technology to another.
Cloud-native: You don't have to host it. Storyblok does that for you.
Internationalization: Excellent multilingual management. You can manage your translations at three different levels: field level, folder level, or space level. This allows you to choose the approach that best suits your project.
Visual Editor: You don't need to know Markdown or any other markup languages to create and manage your content. Storyblok has a visual editor where you can visually manage, organize and preview your content.

And trust me, the Visual Editor looks amazing and your content editors will love it.

Yes, Storyblok has a preview feature where you can see how the content will fit on the page on the fly!

If you want to learn more about Storyblok's features, check out this video (highly recommended!):

How to integrate Storyblok into Eleventy

As a headless CMS, you can integrate Storyblok into any front-end project. However, it is easier depending on the technology you use.

Storyblok works with many modern frameworks and maintains SDKs to install in Vue, Nuxt, React, Next, Astro, SvelteKit, Remix or Gatsby projects. However, there is no official Eleventy SDK (yet).

Therefore, using the JavaScript SDK is necessary to integrate Storyblok into an Eleventy project.

Want to see it in action? Stay tuned! In a future article, I'll explain step-by-step how to integrate Storyblok into an Eleventy project using the JavaScript SDK.

DEV Community: Estela Franco

Create a Blog with Eleventy and Storyblok

Creating the Blog Architecture in Storyblok

Removing the boilerplate content

Creating the initial Blocks: Author and Category

Creating the first stories: Authors and Categories

And what about the Articles?

Creating a Homepage

Wait. And what about SEO?

Create the SEO block

Add the SEO block to the other blocks

Creating the Eleventy project

Setting up and configuring the Eleventy project

1. Create and access your project (and open it using VSCode)

2. Create your package.json file in the root directory and paste the following lines:

3. Install dependencies

4. Create the .env file in the root directory

5. Create the eleventy.js config file

6. Create the src > _data > metadata.json file

7. Create the src > _includes > head.njk file

8. Create the src > _includes > header.njk file

9. Create the src > _includes > footer.njk file

10. Create the src > _includes > layouts > base.njk file

11. Create the src > utils > storyblok.js file

12. Create your src > _data > articles.js file.

13. Create the src > article-pages.njk file

14. Create the src > articles-list.njk file

15. Repeat steps 12 through 14, but this time creating the files related to Authors

16. Repeat steps 12 through 14, but this time creating files related to Categories

17. Create the Home related files

18. Create the src > public > css > styles.css file

Run it locally

Demo and Template Repository

What's next?

Can I use the Storyblok Visual Editor with Eleventy?

How to connect Eleventy and Storyblok

Technical requirements

Creating a project in Storyblok

Creating a project in Eleventy

Setting up and configuring the Eleventy project

Get the API token from Storyblok

How to query the Storyblok data from Eleventy

Create the GraphQL query

Data in Eleventy

Using the Visual Editor from Storyblok

Next steps

Eleventy and Storyblok — My perfect combination

Eleventy, a simpler static site generator

Storyblok, the way to modern content

What's a headless CMS?

Why Storyblok?

How to integrate Storyblok into Eleventy

2. Create your `package.json` file in the root directory and paste the following lines:

4. Create the `.env` file in the root directory

5. Create the `eleventy.js` config file

6. Create the `src > _data > metadata.json` file

7. Create the `src > _includes > head.njk` file

8. Create the `src > _includes > header.njk` file

9. Create the `src > _includes > footer.njk` file

10. Create the `src > _includes > layouts > base.njk` file

11. Create the `src > utils > storyblok.js` file

12. Create your `src > _data > articles.js` file.

13. Create the `src > article-pages.njk` file

14. Create the `src > articles-list.njk` file

15. Repeat steps 12 through 14, but this time creating the files related to `Authors`

16. Repeat steps 12 through 14, but this time creating files related to `Categories`

17. Create the `Home` related files

18. Create the `src > public > css > styles.css` file