zamaneh-builds
v1.0.0
Published
The publishers' static site generator. Performant, memory-efficient builds for huge, content-heavy websites.
Downloads
2
Maintainers
Readme
Zamaneh Builds
Zamaneh builds static websites with large content archives. For this we need a performant, memory-efficient static site generator (SSG) that gives full flexibility to shape API requests, traffic to and from the CMS, and build-time data transformation. With these requirements in mind, Zamaneh Builds was born.
Vision
To the best of our knowlegde, no other SSG on the market supports the generator pattern to enumerate paths or objects in any domain. But the generator pattern is a good idea for certain use cases.
The vision for Zamaneh Builds is to provide a canonical example of why generators are a good idea in certain use cases, so that other SSGs are encouraged to support the generator pattern for enumerating paths (or objects).
Static Site Generator
Zamaneh Builds is a static site generator that supports large (100,000+) article archives. Zamaneh Builds is fast and memory efficient, and allows for flexible content fetch strategies. Zamaneh Builds additionally provides a nice, easy-to-use development and (editorial) preview environment.
- Fast and memory efficient builds.
- Support for huge content archives (100,000+ articles).
- Out-of-the-box support for (editorial) previews.
- Convenient, fast and easy-to-use development environment.
- Uses Nunjucks as a complete and extensible templating language.
Zamaneh Builds is developed with the needs of a publisher, juggling several content-heavy websites and archives that run into the tens to hundreds of thousands of articles, in mind.
Getting started
Create a project
Create a directory for your project using the mkdir command and move into that directory:
mkdir my-project && cd my-project
Installation
Installing Zamaneh Builds into a project requires a package.json file. With the npm
command(provided by Node.js) you can create one by running npm init
.
Now you can install zaamneh-builds
:
npm install zamaneh-builds`
CLI
Run zamaneh-builds dev server
Now you'll be able to start a dev server.
zamaneh-builds dev
as an entry in npm scripts or straight npx zamaneh-builds dev
from your terminal in your project root.
Run zamaneh-builds production build
And you can run a production build.
zamaneh-builds build
as an entry in npm scripts or straight npx zamaneh-builds build
from your terminal in your project root.
Configuration
| Option | Type | Default | Description |
|----------------|----------|-------------|--------------------------------------------|
| src | string
| 'src' | Input directory. |
| dist | string
| 'dist' | Output directory. |
| port | number
| 8080 | Run the dev server on this port. |
| nunjucksConfig | string
| null
| Filepath to a Nunjucks configuration file. |
Example
zamaneh-builds dev --port 3000 --nunjucksConfig lib/nunjucks-config.js
Javascript API
If you don't want to use the CLI you can also create Javascript files from where you can start a dev server and/or run a production build.
Run zamaneh-builds dev server
const { dev } = require('zamaneh-builds');
dev();
Run zamaneh-builds production build
const { buildHtml } = require('zamaneh-builds');
buildHtml();
Configuration
The configuration options are the same. Zamaneh builds exports a defineConfig
function that you can use to create you configuration. This makes sure all default are being set and filepaths are correctly setup for internal usage.
| Option | Type | Default | Description |
|----------------|----------|-------------|--------------------------------------------|
| src | string
| 'src' | Input directory. |
| dist | string
| 'dist' | Output directory. |
| port | number
| 8080 | Run the dev server on this port. |
| nunjucksConfig | string
| null
| Filepath to a Nunjucks configuration file. |
Here is an example on how you would configure zamaneh-builds
when using the Javascript API:
const { buildHtml, defineConfig } = require('zamaneh-builds');
const config = defineConfig({
srcDir: 'src',
outDir: 'dist',
port: 3000,
nunjucksConfig: 'lib/nunjucks-config.js'
});
buildHtml({ config });
Project structure
Zamaneh Builds leverages an opinionated folder structure for your project in order to work. Your project should include the following directories:
data/*
pages/*
With the default configuration you can create these directories inside a src
folder or you can configure your own input directory.
Defining static routes and getting data
Inside the pages
folder, create a subfolder with the name of the page that you'd like to define. In this folder you, create an index.njk
file that is used as the page template.
In the same folder, you can add an index.data.js
file that exports a function, which returns the data for the page. If you return an array of objects, a separate page will be generated for each object in the array, meaning you need to generate a page with dynamic path parameters. Let's explain how this works.
Dynamic routes
A page file can specify dynamic route parameters in its filename to generate multiple pages based on the same template. For example, pages/blog/:id/index.njk
will generate a blog post for every item in the array that is returned from pages/blog/:id/index.data.js
. Note that every item in the array returned from the data file needs to have a property id
.
You are free to us multiple dynamic route parameters as long as every item in the array returned from the corresponding data file has properties resembling the route parameter.
Global data
In the data
folder you can add a JavaScript file that exports a function. Zamaneh Builds makes the return value of that function available in templates in the global
variable. This global
variable is an object with camel-cased attributes, one for each file in the data folder. For example, the data returned by the default export of data/app-navigation-items.js
will be available as global.appNavigationItems
.
Templates
Nunjucks is used as a template language.
In all templates you can use the following variables:
global
: The global data containing all slugified data filenames coming from thedata
folder.page
: The data for the current page returned by theindex.data.js
file.params
: The dynamic route params as an object.url
: The url of the current page.
Nunjucks configuration
It makes sense that at some point you want to extend Nunjucks and use custom template tags, filters and/or globals. You can do this by using the eleventyConfig
configuration option. It accepts the path to a configuration file. The configuration file should export a default function where the the nunjucksEnvironment is passed to as an argument. You can extend the enviroment from there, for more info see the Nunjucks environment documentation.
See below an example where we add a custom filter:
Dev command:
npx zamaneh-builds --nunjucksConfig=lib/nunjucks-config.js
// lib/nunjucks-config.js
module.exports = function (nunjucksEnvironment) {
nunjucksEnvironment.addFilter('slugify', slugify);
};
function slugify(string) {
return string
.toLowerCase()
.replace(/[^\w ]+/g, '')
.replace(/ +/g, '-');
}
From now on you can use the slugify
filter inside your templates:
<h1>{{ 'slugify this heading' | slugify }}</h1>
Will output:
<h1>slugify-this-heading</h1>
Library development
If you want to work on the library, great!
Get started by cloning Zamaneh Builds repository:
git clone [email protected]:ZamanehMedia/zamaneh-builds.git
Run npm install to install all dependencies:
npm install
Npm link the project locally by running npm link
in the root and npm link zamaneh-builds
in the example folder.
See the npm scripts available in the package.json inside the example
folder in order to see different builds.