Goffre

Goffre is a minimal static site generator available to the node.js ecosystem.

It uses handlebars as templating system and markdown + frontmatter as data layer, or whatever you decide to pass to render().

Installation

$ npm install goffre --save

Basic Usage

import { load, render } from "goffre";

(async () => {
    const { pages } = await load();

    try {
        const results = await render({ pages });
        console.log(`Generated ${results.length} pages`);
    } catch (error) {
        console.log("Error generating site", error);
    }
})();

Default paths:

• markdown files: ./data - used by load()
• output folder: ./dist - used by render()
• handlebars views: ./src/views - used by render()

See examples for a more advanced use case, and the documentation for the complete reference.

Data collecting and rendering are separate steps

This is the key for the maximum flexibility: load() gets all the .md files inside the data folder, and populates its return pages each with a unique slug.

The markdown body is available in the content key, and the YAML front matter is destructured - the output of load() of the following file:

---
title: "Goffre | Mini static site generator"
slug: "index"
---
Goffre is a minimal static site generator available to the **node.js** ecosystem.

will be:

{
    title: "Goffre | Mini static site generator",
    slug: "index",
    content: "Goffre is a minimal static site generator available to the **node.js** ecosystem."
}

Note: the markdown body is not yet parsed at this stage.

The render() method writes then every incoming page to {page.slug}.html - you can add further pages to the collected ones, like the text you are reading from the main README.md file of the repository:

const { pages } = await load({ dataPath });
const results = await render({
    buildPath,
    sitePath,
    pages: [
        ...pages,
        {
            title: "Goffre | Mini static site generator",
            description:
                "Goffre is a minimal static site generator available to the node.js ecosystem.",
            slug: "index",
            content: await readFile(path.join("..", "README.md"), "utf8"),
        },
    ],
});

For a better development experience

Goffre does not provide any watching / serving features out of the box, but don't worry.

Serving: if you use webpack for bundling the frontend CSS and JS, just use its dev server - see the configuration file for this very page as reference. If you don't, a simple http-server will do.

Watching: use nodemon to watch the generation script, the data folder and the handlebars views folder:

$ nodemon -e js,json,md,handlebars --watch index.js --watch data --watch src/views

The scripts of package.json will look more or less like:

{
    "clean": "rm -rf dist",
    "dev:client": "webpack serve --mode development",
    "dev:site": "nodemon -e js,json,md,handlebars --watch index.js --watch data --watch src/views",
    "build:client": "webpack --mode production",
    "build:site": "node index.js"
}

Just npm run dev:client and npm run dev:site in two terminal tabs and you are done. Don't forget to npm install the needed dependencies of course!

Examples

• devblog - a personal website with blog posts and project pages
• this page of course