Import data from Storyblok to 11ty

Import Stories and Datasources from Storyblok and use them with 11ty for your static website.

You can download the data and store it ast front matter templates or as global data objects.

This package will work also as Eleventy plugin to add a custom tag for liquid and nunjucks to make it easier to render Storyblok blocks. I'm working also to add such a feature to Javascript templates and to EJS.

Importer

Class StoryblokTo11ty.importer

Parameters

• config Object
  • token String, The preview token you can find in your space dashboard at https://app.storyblok.com
  • [version] String, optional, defaults to draft. It's the Storyblok content version. It can be published or draft
  • [layouts_path] String, optional, defaults to empty string. It's the main path of your layouts in 11ty
  • [stories_path] String, optional, defaults to storyblok. It's the folder where the front matter files are stored
  • [datasources_path] String, optional, defaults to _data. It's the folder where the global data files are stored
  • [components_layout] Object, optional, defaults to empty object. An object with parameter -> value to match specific component to specific layouts. For example {root: 'layouts/root.ejs', news: 'layouts/news_entry.ejs'}. The script will use the name of the component as default layout for each entry. An entry made with the root component will have by default layouts/root;
  • [storyblok_client_config] Object, optional, defaults to empty object. You can pass a custom object of settings for the config parameter of the Storyblok JS Client.

Stories Data Transformation

Stories are fetched from Storyblok api and the content propert of objects is renamed as data because using just content won't work well with 11ty. The story object will have 3 new properties used by 11ty:

• layout String. The name of the folder inside _include where you have stored your layouts;
• tags String. The name of the component of the entry, used to support the collections feature of 11ty;
• permalink String. The permalink of the entry. This value uses the real path if set, otherwise it falls back to the full slug.

Method StoryblokTo11ty#getStories

With this method you can get all the stories from your space as an array of objects. Stories are transformed in order to let you use layouts and permalinks.

Parameters

• [options] Object, optional.
• [options.component] String, optional. Set this parameter with the name of a component to get just the entries made with it
• [options.resolve_relations] String, optional. Resolve multiple levels of content by specifying comma-separated values of component.field_name according to your data model.

Return Promise. The response of the promise is an array of transformed entries.

Examples

// Example of Global Data File in the _data directory
module.exports = async () => {
    const StoryblokTo11ty = require('storyblok-11ty');
    const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});
    
    return await sb.getStories();
}

// Alternative example to return just the pages made with the component called news
module.exports = async () => {
    const StoryblokTo11ty = require('storyblok-11ty');
    const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});
    
    return await sb.getStories('news');
}

Method StoryblokTo11ty#storeStories

With this method you can store all the stories from your space as front matter .md files. Stories are transformed in order to let you use layouts and permalinks.

Parameters

• [options] Object, optional.
• [options.component] String, optional. Set this parameter with the name of a component to get just the entries made with it

Return Promise. Return false if something went wrong in the process, otherwise true.

Examples

// Storing all of the entries
const StoryblokTo11ty = require('storyblok-11ty');
const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});

sb.storeStories();

// Storing just the news
const StoryblokTo11ty = require('storyblok-11ty');
const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});
    
sb.storeStories('news');

Method StoryblokTo11ty#getDatasources

With this method you can get all the datasources or one in particular as an array of objects. For each datasource the script will retrieve all the dimensions.

Parameters

• [datasource_slug] String, optional. The slug of the datasource you want to retrieve.

Return Promise. The response of the promise is an object with all the datasources or an array of entries in case you are requesting a single datasource.

Examples

// Example of Global Data File in the _data directory
module.exports = async () => {
    const StoryblokTo11ty = require('storyblok-11ty');
    const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});
    
    return await sb.getDatasources();
}

// Alternative example to return just the datasource called categories
module.exports = async () => {
    const StoryblokTo11ty = require('storyblok-11ty');
    const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});
    
    return await sb.getDatasources('categories');
}

Method StoryblokTo11ty#storeDatasources

With this method you can get all the datasources or one in particular. The datasources will be stored as json files in the _data folder or in the one specified through the datasources_path parameter of the Storyblok11Ty instance. Each datasource will be stored in a file with its name and in case you are requesting all of the datasources the name of the file will be datasources.json.

Parameters

• [datasource_slug] String, optional. The slug of the datasource you want to retrieve.

Return Promise. Return false if something went wrong in the process, otherwise true.

Examples

// Store all of the datasources in a single datasources.json file
const StoryblokTo11ty = require('storyblok-11ty');
const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});

return await sb.storeDatasources();

// Storing the datasource called categories in categories.json
const StoryblokTo11ty = require('storyblok-11ty');
const sb = new StoryblokTo11ty.importer({token: 'your-space-token'});

sb.storeDatasources('categories');

Eleventy Plugin

Class StoryblokTo11ty.plugin

Parameters

• config Object
  • blocks_folder String, The folder of the blocks layouts. It should include the includes folder path just if you are using Nunjucks.

// Example of Global Data File in the _data directory
const StoryblokTo11ty = require('storyblok-11ty');
const sb = new StoryblokTo11ty.plugin({blocks_folder: 'components/'});

Custom tag for blocks fields

If you have a field of type block and you have several blocks inside it, you might want to output all of them using a different layout file for each block. In order to achieve this you can use a custom tag for Liquid and Nunjucks layouts.

sb_blocks for Liquid

The custom tag sb_blocks can be used like this {% sb_blocks name_of_blocks_field %} and it will loop through all the blocks inside the field. For each block it'll include a template with the same name as the slugified component name. If your block is called Home Banner the tag will look for the template home-banner.liquid inside the _includes/block/ folder or inside includes/your_custom_folder/. You can specify your_custom_folder passing the parameter blocks_folder to the Storyblok11Ty instance like in the example below. You don't need to add your includes folder path into the blocks_folder parameter because 11ty will take care of that for you.

The block fields will be passed to the layout under the object block. If your block has a field called heading you can retrieve its value referencing to it as block.heading.

const Storyblok11Ty = require("storyblok-11ty");
const sbto11ty = new Storyblok11Ty.plugin({blocks_folder: 'components/'});

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(sbto11ty);
};

sb_blocks for Nunjucks

The custom tag sb_blocks can be used like this {% sb_blocks name_of_blocks_field %} and it will loop through all the blocks inside the field. For each block it'll include a template with the same name as the slugified component name. If your block is called Home Banner the tag will look for the template home-banner.njk inside the _includes/block/ folder or inside includes/your_custom_folder/. You must specify your_custom_folder passing the parameter blocks_folder to the Storyblok11Ty instance like in the example below. You must add your includes folder path into the blocks_folder parameter to make the tag work properly, unfortunately it's not the same as for Liquid.

The block fields will be passed to the layout under the object block. If your block has a field called heading you can retrieve its value referencing to it as block.heading.

const Storyblok11Ty = require("storyblok-11ty");
const sbto11ty = new Storyblok11Ty.plugin({blocks_folder: '_includes/components/'});

module.exports = function(eleventyConfig) {
  eleventyConfig.addPlugin(sbto11ty);
};