Enginær

Enginær is a simple static website engine.

Motivation

While developing, my motivation has been to easily publish a new post or a new page, like sending a new commit message to a git repository.

I like writing blogs, but I cannot have enough time. I know writing markdown is so easy and also the markdown document has a human-readable structure. Moreover, markdown documents also support many components that using in HTML documents is not easy such as tables, images, and lists.

Challenges

Creating a blog engine there are some challenges. The first one is to create an automation for converting markdown documents into HTML documents. For this operation, I am using the marked library. The second challenge is creating a simple and extendable template system. The mustache library is the simple and logic-less template engine that is suitable for this challenge.

Apart from all of the other challenges, executing operations in parallel or serial order I need to develop an automated pipeline system. gulp is a flexible and repetitive system. I selected gulp and the main part of the project stands a gulp plugin.

Usage

The usage of the tool is very easy if you have selected your blog template or blog layout and its style.

Install

npm install --save-dev enginaer

Import References

First of all import all required references.

const { series, parallel, src, dest } = require("gulp");
const clean = require("gulp-clean");
const enginær = require("enginaer");

Configuration

The configuration is very basic and user friendly.

const config = {
    "base": __dirname,
    "page": {
        "path": "./page/**/*.md",
        "visitor": "./page/**/*Visitor.js",
        "marked": {
            breaks: true,
            smartLists: true,
            headerIds: false
        }
    },
    "template": {
        "path": "./template/*.mustache",
        "helpers": "./template/templateHelpers.js"
    },
    "site-title-prefix": "Enginær - ",
    "site-name": "Enginær Demo",
    "base-url": "https://blog.tatoglu.net/enginaer/"
};

Configuration Description

| Attribute | | Description | Type | | :--- | :---: | :--- | :-- | | base | | The base path of the resources. Usually you can set __dirname. | string | | page | | The page object | object | | | path | The page folders paths. | glob | | | visitor | The page visitors paths. | glob | | | marked | The marked configuration. Reference: markedJS Options | object | | template | | The template object. | object | | | path | The templates paths. | glob | | | helpers | The render helper functions paths. | glob | | site-title-prefix | | The website title prefix. | string | | site-name | | The name of the website. | string | | base-url | | The website base url. | string |

For more details about glob data type.

Execution Steps

After defining the configuration, there are there main steps.

Initialization

var enginær = new Enginaer(config);

In this step, the engine is initialized. While initilization, if the engine is faced any invalid or missing configuration, will throw an exception.

Loading Resources

enginær.load();

This step is required for loading mandatory resources validation and processing in the engine. While loading resources engine could throw any exceptions, if the resource is not valid.

The loading steps work in the following order.

1. Templates
2. Template Helpers
3. Page Visitors
4. Pages

Generation

enginær.generate();

At the end, the engine is ready to generate web site pages.

Sample Gulpfile

For putting all execution step together the sample gulp file is below.

const outputPath = "../dist/";

// Gulp Step 1 - Clean old files.
function cleanAll() {
    return src(outputPath, { allowEmpty: true })
        .pipe(clean({ force: true }));
}

// Gulp Step 2 - Copy all required assets.
function copyAssets() {
    return src(["./assets/css/*.css",
        "./assets/js/*.js",
        "./assets/img/*.png",
        "./assets/img/*.jpg"], { base: "./assets/" })
        .pipe(dest(outputPath));
}

// Gulp Step 3 - Enginær
function generate() {

    // Initialize enginær engine.
    var enginær = new Enginaer(config);

    // load required resources (templates, template helpers, pages, and page visitors.)
    enginær.load();

    // Generate web site pages.
    return enginær.generate()
        .pipe(dest(outputPath));
}

exports.default = series(
    cleanAll,
    parallel(copyAssets, generate)
);

Customization

The enginær.generate method return file stream. If you want to customize the output, you should add new pipe steps.

The other customization options are Page Visitors and Template Helpers.

Page Visitors

This customization step provides adding new key-value pair in the page metadata. The page visitors are applied for all pages after loading and for each page object.

The page visitor must be extend from BasePageVisitor class.

class BasePageVisitor {
    name: string;
    visit(page:Page):Error | undefined;
}

Template Helpers

This customization step provides helpers for rendering mustache templates. There is one restriction that must be returns an object such as the below example.

module.exports = {
    "helper-name": function () {
        return "sample-code";
    }
};

Execute

After creating gulpfile.js the system is ready to execute. For executing follow the below steps.

# Step 1. Install NPM Packages
npm install

# Step 2. Install Gulp CLI
npm install --global gulp-cli

# Step 3. Execute Enginær
gulp

That's all. For demo you can visit Enginær Demo site.

Support

For supporting me, you can add an issue for bug cases or new feature requests.