@static-pages/core
v7.0.0
Published
General purpose static pages renderer.
Downloads
39
Readme
Static Pages / Core
Yet another static pages generator? Yes! Because I browsed the whole jamstack scene, but could not find one which
- can read input from any source (YAML, JSON, front-matter style markdowns, database etc.)
- can render with any template engine (Twig, ejs, Pug, Mustache etc.)
- written in JS (preferably TypeScript)
- easy to extend with JS code
- supports incremental builds
- uses MVC pattern
- learning and using is easy (Gatsby, Hugo, Jekyll, Eleventy etc. are so cool but harder to learn and configure)
And because I wrote a ton of custom static generators before; I tought I can improve the concepts to a point where its (hopefully) useful for others.
This project is structured as a toolkit split to many packages, published under the @static-pages namespace on NPM. In most cases you should not use this core package directly, but the @static-pages/starter is a good point to begin with.
Where should I use this?
This project targets small and medium sized websites. The rendering process tries to be as fast as possible so its also useful when you need performance.
Usage
import fs from 'node:fs';
import path from 'node:path';
import staticPages from '@static-pages/core';
staticPages({
from: [
{ title: 'About', url: 'about', content: 'About us content' },
{ title: 'Privacy', url: 'privacy', content: 'Privacy content' },
],
controller(data) {
data.now = new Date().toJSON();
return data;
},
to({ title, url, content, now }) {
const fileName = path.join('public', url + '.html');
const fileContent = `<html><body><h1>${title}</h1><p>${content}</p><p>generated: ${now}</p></body></html>`;
fs.mkdirSync(path.dirname(fileName), { recursive: true });
fs.writeFileSync(fileName, fileContent);
}
})
.catch(error => {
console.error('Error:', error);
console.error(error.stack);
});Notes
The usage example above does a rough presentation only and not considered to be a production ready snippet. Helpers to read and write documents are provided in separate packages, eg. @static-pages/io.
Documentation
For detailed information, visit the project page.
staticPages(...routes: Route[]): Promise<void>
Each route consists of a from, to and a controller property matching the definition below.
interface Route<F, T> {
from: Iterable<F> | AsyncIterable<F>;
to(data: T): void | Promise<void>;
controller?(data: F): undefined | T | Iterable<T> | AsyncIterable<T> | Promise<undefined | T | Iterable<T> | AsyncIterable<T>>;
}The controller may return with multiple documents, each will be rendered as a separate page. Alternatively it may return undefined to prevent the rendering of the current document.
Missing a feature?
Create an issue describing your needs! If it fits the scope of the project I will implement it.