Eleventy + Netlify CMS Static Site Generator

Stack

This is a custom solution for static, NetlifyCMS-enabled websites developed by and for idiaz.roncero.

It is itself a fork of eleventy-netlify-boilerplate.

It uses gulp for asset handling, especially image handling (resize / minify). This could and should be moved into Eleventy's own build system in the future.

For the front-end, it depends on huesos, a custom SCSS framework. The framework configuration overrides are handled on /src/assets/scss/_config.scss.

For JavaScript, it uses Parcel CLI without any further configuration. We intent to be able to write ES6 and import modules without having to configure a full-featured and unneded Webpack/SPA configuration, since we don't need most of Webpack's bells and whistles. Of course, you are free to ignore this and set your own JS toolbox.

Image assets

Image handling is one of the biggest issues on static site generators. Without a live server-side tools like Imagick, the usual transform/crop/resize become a problem.

This project stores all image assets that will need operations on src/public and exposes a images.config.js config file to decide which strategy to follow (git lfs can be either true or false) and how many crops are needed.

This is a sample images.config.js:

{
    sourceDir : './src/public/images', // The original source of the assets
    relativeSourceDir : '/public/images', // The real, final path
    lfs : true, // Wether to use lfs or not 
    nf_resize: 'fit', // If LFS is true, which resize algorithm to use
    sizes : [ // An array of sizes
        {
            name: 'large', // Name of the size, will also be the destination sub-folder
            width: 1400, // The image width
            height: false, // The image height, or false to auto-calculate it
            isResponsive: true, // Should this image be used on the <picture> responsive element
            customQuery: { // Optionally, for LFS, a custom query to replace the default one
                width: 300,
                path: 'fit&w=300&h=300', 
                width2x: 600,
                path2x: 'fit&w=600&h=600'
            }
        }
        {
            name: 'icon',
            width: 50,
            height: 25,
            isResponsive: false
        },
    ],
}

Using gulp

If your site is not heavy on images, you can use the image scripts in order to generate all the needed crops and resizes and .webp versions.

This sytem expects the user to upload to src/assets/img only the larger image that needs to be available (by default, 1400px wide @ 2x = 2800px wide).

It will automatically create a normal and @2k version of four sizes: thumbnail, small, medium and large.. It will also make a .webp copy of every file.

If it can't enlarge an image, it will silently fail and continue.

To auto-generate all the markup needed for responsive images (we assume 100w as the sizes attribute), use the custom picture nunjucks filter:

    {{ '/path/to/image/asset.png' | picture | safe }}

We use <picture> instead of the leaner <img srcset="" > syntax in order to be able to use a srcset for .webp, a .jpg srcset fallback for less-capable browsers and finally a <img> tag for legacy browsers.

Note that safe filter is needed in order to output HTML.

For non-responsive images, an img filter is also provided in order to output both a .webp and a .jpg version;

    {{ '/path/to/image/asset.png' | img | safe }}

Using LFS

Netlify provides support for large media using git lfs.

You will need to set up Git LFS in order for Large Media to work. Follow the instructions on the official Netlify Docs. Do not ever try to fork/copy a repo with a initialized LFS/Large Media: it won't work.

You can use the above mentioned {{ picture }} and {{ image }} filters safely: they will output queried URL's using Netlify's large media instead. This way, you can safely switch between lfs and non-lfs without having to rewrite your codebase.

Commands

yarn build triggers a complete build of all the static and compiled assets. It will look at the lfs value of images.config.js to decide wether to perform image conversions.

yarn watch starts the watch process for both Eleventy and sass.

yarn serve starts the watch process + a Browserify server for live-testing.

yarn debug triggers a eleventy build with the DEBUG flag for debugging.

yarn css compiles sass into css with sourcemaps and nested output.

yarn css:prod compiles sass into css without sourcemaps and compressed. It is used on "build" command.

yarn css:watch starts a watch process for SASS. It is used on "watch" command.

yarn css:post runs postcss plugins, using .browserlistrc for browser usage and postcss.config.js to load plugins (postcssPresetEnv and stylelint by default). It is used on "build" command.

yarn images runs gulp processImages tasks. It cleans the images, creates webp and minified versions and generate all the configured resizes and crops. It can become a rather lengthy and memory-heavy process, so use it wisely and switch to another solutons (LFS, third-party) if your image assets grow.

yarn images:clean runs gulp cleanImages task, deleting all images except the originals.

yarn images:resize performs gulp resizeImages task, creating all the configured resizes and crops from the original images.

yarn images:minify runs gulp minifyImages. Creates webp versions and minifies jpg and pnf files.

yarn pwa and yarn images:favicons both run a gulp process that will generate all favicons needed and all the manifest files for service workers / search engines. Please note this command needs to be manually run once on every favicon.jpg change because it is not part of the build process (in order to make it faster).

yarn js:build runs a Parcel cli command that takes /assets/js/script.js and outputs a script-bundle.js file transpiled, tree-shaked and module-bundled.

TODO

• Rewrite LFS Query handling