⚠️ This is a work in progress and not tested in production. It's not likely that I will ever finish it (I can recommend Gatsby instead), but this might be useful to learn how a static site generator can be built and how to structure a CLI heavy lib.

☄️ A batteries included static site generator for Node.js

• Install
• CLI
• Usage
  • Configuration
  • Variables
  • Pages
  • Layouts
  • Asset pipeline
  • Static data
• Motivation
• License

Either install as global package or dependency of your project.

npm install -g zelos
# or
npm install -D zelos

Starts the build process creating production ready files in the public folder.

zelos build [options]

Pages with draft: true will not be built by default. To build drafts add this option.

Starts a local webserver serving the content from the public directory. Don't use this for production!

zelos serve

Bootstraps a new project in the given path or current directory if no path is specified. Creates necessary folders, config and default layouts.

zelos new [path] [options]

As it's advised to set an siteUrl you can directly set the siteUrl during initialization. The value gets written to the config.json.

There are three places Zelos is looking for configuration options. First of all Zelos extracts information from the package.json file if present. The following fields are mapped to Zelos config options:

homepage => siteUrl
author => (parsed) author
description => description
name => siteName

Additionally the whole zelos config can be placed in the package.json using zelosConfig as field name.

Finally Zelos is looking for a config.json file to extract configuration options from. The priority is as follows (low to high):

package.json > zelosConfig > config.json > CLI

There are some options such as drafts which can be set via CLI. Those have the highest priority and overwrite corresponding options listed in any of the places above.

By default you don't have to set any options except siteUrl. The siteUrl is needed to generate a valid sitemap and RSS feed as well as permalinks.

All options have sensible defaults to generate a solid static website but can be adjusted as needed.

{
  "assetDir": "assets",
  "contentDir": "content",
  "defaultLayout": "default",
  "defaultPageType": "page",
  "drafts": false,
  "language": "en",
  "layoutDir": "layouts",
  "minify": true,
  "publicDir": "public",
  "rss": true,
  "rssFilename": "feed.xml",
  "rssRegex": "\.md$",
  "serviceWorker": true,
  "sitemap": true,
  "staticDir": "static"
}

Every site requires an _base.html layout. This file should contain the base html structure (head, body etc.) and is used for every page. This layout can be adjusted as needed. All site and page variables are available.

Additionally you can create your own layouts. To reference a layout add layout: NAME to the frontmatter of each page which should use your layout. By default every page uses the default.html layout. This can be changed in the configuration. To explicitly not use a layout add layout: null the the corresponding pages frontmatter. The _base.html will always be applied.

Every layout should contain the {{{content}}} handlebars expression. This will be replaced with the page content (or layout in case of _base.html).

Zelos has a simple builtin asset pipeline. Any files in assets/css/ and assets/js/ will be processed automatically.

All files in the static folder will be copied to the public folder without further processing. Use this for static files such as favicons, images and other data needed in production.

There are a lot of awesome generators out there such as Gatsby, Hugo, Hexo and many more. You might ask why another static site generator.

.. This package aims for a zero config experience to quickly create static websites. In contrast to the bundler ecosystem (Webpack, Parcel, et al.) most static site generators written for Node.js are heading to a plugin based architecture. This makes them very flexible but require some decent amount of time to configure in the first place.

MIT © Lars Graubner