Static Pages / Core

This package contains only the core; this means it does not provide CLI support or readers and writers. You can import this library to your JS project then add your own controllers, readers and writers.

Yet another static pages generator? Yes! Because I browsed the whole jamstack scene, but could not find one which

1. uses MVC pattern
2. can read input from any source (YAML, JSON, front-matter style markdowns, database etc.)
3. can render with any template engine (Twig, ejs, Pug, Mustache etc.)
4. supports incremental builds
5. has a flexible CLI tool (see @static-pages/cli on npm)
6. has a Docker image (see staticpages/cli on dockerhub)
7. written in JS (preferably TypeScript)
8. easy to extend with JS code
9. 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.

Where should I use this?

This project targets small and medium sized projects. The rendering process tries to be as fast as possible so its also useful when you need performance.

Documentation

Visit the project page.

Usage

• Readers provides an iterable list of page data.
• Controllers can manipulate and extend each data object.
• Writers render the final output for you.

import staticPages from '@static-pages/core';
import markdownReader from '@static-pages/markdown-reader';
import yamlReader from '@static-pages/yaml-reader';
import twigWriter from '@static-pages/twig-writer';

staticPages({
    from: markdownReader({
        pattern: "pages/**/*.md"
    }),
    to: twigWriter({
        view: "content.html.twig",
        viewsDir: "path/to/views/folder",
        outDir: "path/to/output/folder",
    }),
    controller(data) {
        data.timestamp = new Date().toJSON(); // adds a "timestamp" variable
        return data; // returning the data is required if you want to send it to the renderer
    }
}, {
    from: yamlReader({ // assume we have the home page data in yaml format.
        pattern: "home/*.yaml" // <-- reads home/en.yaml, home/de.yaml, home/fr.yaml etc.
    }),
    to: twigWriter({
        view: "home.html.twig",
        viewsDir: "path/to/views/folder",
        outDir: "path/to/output/folder",
    }),
    controller(data) {
        data.commitHash = yourGetCommitHashFn();
        return data;
    }
})
.catch(error => {
    console.error('Error:', error);
    console.error(error.stack);
});

staticPages(...routes: Route[])

Each route consists of a from, to and optionally a controller property matching the definition below.

type Data = Record<string, unknown>;
type Route = {
    from: Iterable<Data> | AsyncIterable<Data>;
    to(data: IteratorResult<Data>): void | Promise<void>;
    controller?(data: Data): void | Data | Data[] | Promise<void | Data | Data[]>;
};

Implementation Notes

• The controller may return an array of Data objects; each will be rendered as a separate page. Alternatively it may return void to prevent the rendering of the current data object.

• The writer function provided in the to property is expected to conform to the JavaScript iterator protocol in order to work. Specifically, this means that the function will be invoked with a { value: Data } parameter for each data object, and will receive a { done: true } parameter when it has finished processing the data and there is no more pages to write.

Missing a feature?

Create an issue describing your needs. If it fits the scope of the project I will implement it or you can implement it your own and submit a pull request.