A static site builder to produce a combined documentation site for ZUI and ZAPI projects. It was conceived to separate documentation from the toolkit projects to keep things lean and organized.
The main tooling behind the static site generator is Eleventy, sometimes written as 11ty. 11ty takes in templates, data (.json, .md, .html etc.) and assets, then outputs lightweight performant static HTML pages. For more info see Eleventy.
git clone https://github.com/Zywave/booster.git
cd booster
yarn install
Launch site locally and watch for changes:
yarn run watch
Build or re-build site, _site
folder is where output is placed:
yarn run build
Run 11ty in debug mode, one command for windows and one for *nix:
yarn run debug:windows
yarn run debug:nix
- Static HTML files are output to a
_site
folder, whether you're building for production or running the project locally the site will be served from this directory. Files in the_site
folder will persist until removed; if you delete files insrc
it may still be accessible in the_site
folder and therefore in your site, be careful to delete_site
and re-build if necessary.
Templating syntax:
{{ variableName }}
Expression syntax:
{% if thing %}
{{ thing and thing }}
{% endif %}
Nunjucks is a templating engine that allows for variable content, expression like behavior, parent child template extension, etc. for finer control of the outputted HTML. It's sort of a meld of HTML, JS and a simplified front end framework.
For additional info see nunjuck's docs.
Frontmatter is added to the top of .njk, .md, and several other supported files. It is written in YAML, it's essentially key value pairs, starts and ends with ---
and looks as such:
---
title: "I am a title"
subTitle: Quote marks around values are optional
avoid: Camel case good, kebab case or hyphens in keys bad
---
Certain keywords in frontmatter are specific to 11ty.
- Using
_data
folder- Add
trolls.json
to the_data
folder and it will be globally accessible in your .njk as:
- Add
{{ trolls.favorites.names }}
- Frontmatter as data
- Frontmatter values are accessible as data in .njk files too:
---
ninjaTurtle: leonardo
---
{{ ninjaTurtle }}
Pagination is an 11ty concept to automatically generate pages by looping through a piece of data. For instance if we make template.njk
and feed it data via _data/componentRegistry.json
, we can output different pages using pagination and link to them using their permalink frontmatter value. The alias
references the current item in the loop:
---
pagination:
data: componentRegistry.components
size: 1
alias: component
permalink: {{ component.commonName | slug }}
---
<h1>{{ component.commonName }}</h1>