The JAMstack architecture
The principles of JAMstack static site.
What is JAMstack?
Eleventy, as most static sites, relies on an architectural paradigm called JAMstack, an acronym meaning: a modern web development architecture based on client-side JavaScript, reusable APIs, and prebuilt Markup.
see Mathias Biilmann & Phil Hawksworth book: Modern Web development on the JAMstack. .
In the JAMstack architecture, JavaScript is used not only in the browser for interactivity and presentation but also to build all the files of the site this is the case of Eleventy. Other generators use different languages: Go, Python, etc. ; the APIs are the programming interfaces to Node packages Eleventy itself is a Node package. or other frameworks used as a back end; Markdown is used to set the content of each page of the site, with a settings part (front matter) using either JavaScript or a description language like YAML or TOML and a template part there are many templating systems: Liquid, Nunjucks, Hanbdlebars, Pug, etc. .
11tyTips architecture
Trying to stay as simple as possible, 11tyTips is built using a minimal set of the JAMstack architecture: JavaScript, backed by the Node ecosystem, Nunjucks, as templating system, and Markdown as content markup language. It doesn’t follow the canonical dispatching of files promoted by Eleventy and most satic site generators (data, templates, contents), but follows a pattern examplifying the JAMstack paradigm.
The source
directory design reflects the JAMstack categories:
- make contains JavaScript modules to be used during the build process and is split in two directories: Eleventy modules (
11ty
) and 11tyTips modules (lib
). This is also where the initial JavaScript file firing the building process is located. Instead of.eleventy.js
this file is namedmake.js
(without the starting dot because it is not hidden). - matrix gathers, in
./
andparts
directories, all the templates producing the site HTML files; plus the Javascript and CSS files concatenated and minified (assets
). - matter contains the Markdown files of all site posts (
pages
subdirectory), plus some files they include (parts
).
I sometimes like to call it the 3M directory all of its subdirectory having names begining with an m letter, enumerating these directory names sounds like a slogan: make matrix matter(s)!
. All subdirectories of the three first level directories follow a consistent naming scheme:
- assets for directories containing both script files, style files and files not to be processed and just to be passthru copied to output site;
- scripts for JavaScript files and, eventually, other scripting language files
- styles for Cascading stylesheet files and, eventually, other styling language files (SCCS, etc.)
- parts for partial files to be included by other files.
This structure departs deliberately from what is generaly adopted by static sites built with Eleventy see, for instance, Eleventy base blog structure , examplifying the versatility of the tool Eleventy configuration object has two properties allowing this precious flexibility: dir.data
and dir.includes
. : Eleventy doesn’t lock you into a predefined scheme and let you express your specific needs with ease.
11tyTips has been designed to offer the maximum of flexibility and consistency in the development phase, keeping a strong separation of concerns as to ease any needed refactoring and modification of the code. The site source tree gives an overview of the source directory hierarchy.
Following these configuration options leads to a command line requiring the --config
argument:
npx eleventy --config=make/11ty/make.js