← Journal

A guide to Minimaly, my Eleventy starter

It's been a few days since i released my Eleventy starter called Minimaly.I'm thrilled by all the positive feedback. Some people were asking about Eleventy, others about design tokens, so here is the guide about how i have put all these pieces together to build my starter.

# Project structure

First things first, my project structure

+-- src
    +-- _data
    +-- _includes
    +-- feed
    +-- filters
    +-- images
    +-- js
    +-- posts
    +-- scss
    blog.njk
    index.njk
.babelrc
.eleventy.js
.gitignore
.README.md
gulpfile.babel.js
package.json

package.json

It contains all the packages, eleventy, plugins for the gulp tasks, others to minify html, format date ...

gulpfile.babel.js

Tasks compiler for scss and js files and ouput them directly in _includes eleventy folder. You can find doc about it on gulp npm

.eleventy.js

Here is where some of the magic happen ! in this file, place in the root of your project, you can configure many things. You can find all about it in the very well done documentation about eleventy. It's a js file where you can export all your eleventy configuration. I won't go over this file cause i think the eleventy documentation is already very well done and most of the configuration talk for themselves.

module.exports = function(config) {
    ...
}

# Data is everything - official doc

One of the many amazing things with eleventy, is the way it handles data. In your src folder you can add a _data folder. In this folder you can then add all the .json or .js files that will contain the data you need to use.

In my project i have added a src/_data/site.json where i store global data like the site title, the logoPath, the maxPostsPerPage that i use to retrieve the last posts on my hompeage...

If you want to display the posts as grid you can set showAsGrid to true, if you set it to false it will render posts as list. You can choose if you want to display image of a post postWithImage if you set it to false, the posts render on the homepage and blog page will no longer use the images from you posts (if you add one in the first place of course)

You can name site.json any name you want, juste keep it consistant. You can also add many different json files depending on which data you wanna store. Then you can simply call it in your template as site.title or site.logoPath and it will return your data.

# Design Tokens

In the _data folder, i also add a tokens.json file. This file as nothing to do with eleventy in particular. It is a way to handle design core data in your project.

I have discover design tokens with Andy Bell Eleventy starter Hylia. It was first initiate by Jina Anne who wrote a post about it "In search of a living design system", you should read this post if you want to understand why this system is amazing. There is also npm packages that now exist to handle it but be aware that those packages are for larger projects to handle and share the core design between many apps or websites.

Design tokens, as i say earlier, gives you the possibilites to store your design core data such as colors, fonts, sizes, breakpoints and more, compile it, then use it in your style system.

So in my project i have src/_data/tokens.json file, and then in my package.json on npm run serve i run a command to compile this json to scss and send the result in src/scss/settings/_tokens.scss.

Then, in src/scss/settings/_mapping.scss, i map each of the declared data and store it in a sass variable like $minimaly-colors: map-get($tokens, 'colors');

Then for each of those declarations, i add a specific file where i handle this variables. For exemple, in _colors.scss file, i loop over $minimaly-colors in a :root declaration (global variables) so i can later use them like var(--colors-dark)

# All set !

Well, that's it ! You can now play around, add some more data or design tokens. I hope that's clear enough so you don't get crazy trying to understand. If not, let me know on twitter

Have fun !