Build Better Prototypes with Veams

Yet another static site generator - fast, simple and powerful.

Mangony fulfills just one task: It takes handlebars templates and compiles them to an output directory.

Features

Think of Assemble (grunt-assemble) with a smooth mango juice - yummy.

Mangony can be used in Grunt, Gulp or standalone as npm module.
By using the provided development server (express) every change is completed in no time, no matter how many pages you have in your project.
Only changed pages get compiled.
Creation of deep ids is possible for all types.
For every type (data, partials, layouts, pages) Mangony adds a watcher (chokidar).
HJSON is available.
Handlebars version 4.x is integrated.
Markdown pages with handlebars are supported.
Markdown-it, markdown-it-attrs and markdown-it-named-headers are available.
Mangony provides many handlebars-helpers:

Setup in NodeJS

Node Installation

Install Mangony with

npm install mangony --save-dev

For the installation of the Grunt plugin, see grunt-mangony.

Node Usage

Just create a new instance of Mangony:

const app = new Mangony();

Then render your files or start your development server:

app.render();

When using the default options your files get compiled.

Node Examples

dev.js

Let`s say we want to develop a new app.

const Mangony = require(`mangony`);
const app = new Mangony({
    allow: {
        YFMLayout: false,
        YFMContextData: false
    },
    compileStaticFiles: false
    cwd: `src`,
    dest: `dist/`,
    devServer: {
        start: true
    },
    watch: true,
    types: {
        data: {
            dir: 'data',
            files: [
                '**/*.json',
                '**/*.hjson'
            ]
        },
        partials: {
            dir: 'partials',
            files: [
                '**/*.hbs'
            ]
        },
        pages: {
            dir: 'pages',
            files: [
                '**/*.hbs',
                '**/*.md'
            ]
        },
        layouts: {
            dir: 'layouts',
            files: [
                '**/*.hbs'
            ]
        }
    },
    helpers: [
        'helpers/*.js'
    ]
});

app.render();

When using the devServer options all routes get registered.

Now you can open your browser at localhost:3000 and navigate to the page you want to change. The url is the path to your page without a file extension (i.e. /index).

prod.js

Let`s say we want to build our app.

const Mangony = require(`mangony`);
const app = new Mangony({
    allow: {
        YFMLayout: false,
        YFMContextData: false
    },
    cwd: `src`,
    dest: `dist/`
    types: {
        data: {
            dir: 'data',
            files: [
                '**/*.json',
                '**/*.hjson'
            ]
        },
        partials: {
            dir: 'partials',
            files: [
                '**/*.hbs'
            ]
        },
        pages: {
            dir: 'pages',
            files: [
                '**/*.hbs',
                '**/*.md'
            ]
        },
        layouts: {
            dir: 'layouts',
            files: [
                '**/*.hbs'
            ]
        }
    },
    helpers: [
        'helpers/*.js'
    ]
});

app.render();

Now you can find the complete rendered output in the destination folder.

Setup in Grunt

Grunt Installation

npm install grunt-mangony

Grunt Options

All options of Mangony are available.

Grunt Usage

You can enable this plugin in the Gruntfile.js of your project like that:

grunt.loadNpmTasks('grunt-mangony');

Grunt Examples

To use a development server and a build task you can add the following configuration:

mangony: {
    options: {
        cwd: 'src',
        dest: 'dist',
        types: {
            data: {
                dir: 'data',
                files: [
                    '**/*'
                ]
            },
            partials: {
                dir: 'partials',
                files: [
                    '**/*.hbs'
                ]
            },
            pages: {
                dir: 'pages',
                files: [
                    '**/*.hbs'
                ]
            },
            layouts: {
                dir: 'layouts',
                files: [
                    '**/*.hbs'
                ]
            }
        },
        helpers: [
            'helpers/*.js'
        ]
    },
    dev: {
        options: {
            compileStaticFiles: false,
            devServer: {
                start: true
            },
            watch: true
        }
    },
    dist: {
        options: {
            compileStaticFiles: true,
            watch: false
        }
    }
}

To keep the dev task alive you should integrate a watch task or another keep-alive task like (grunt-contrib-watch).

Setup Examples

Static Website

It is very easy to setup a static website with Mangony. Just install Mangony or use Veams.

Technical Documentation

An automated technical documentation is something a developer sometimes needs to deliver. So here is how it done:

Demo

Is coming soon!

Setup

That is really easy.

Just enable allow.YFMLayout and allow.YFMContextData in options.
Add the partials or pages to the types.pages.files array.
Add a new documentation layout (see Mangony Docs Boilerplate).
Add all of your variations to a HJSON file next to your partial or page.
Add a README.md file next to your partial or page.

The setup is done.

Usage

Now how can you generate these documentation pages? Now the magic begins:

Just add the following to your YFM:

contextData: "my-data-file"
layout: "lyt-docs"

Options

allow.YFMLayout (`Boolean`)

default: false

Add the possibility to reference layouts in YAML front matter. `` will be replaced in your referenced layout with the content of the page.

allow.YFMContextData (`Boolean`)

default: false

Flag to add a specific data context for your page by referencing a data file id in YAML front matter.

assets

default: "./"

Path to your assets in your destination directory.

collections

default: []

Add your own collections which can be used in YAML front matter.

compileStaticFiles

default: true

Enable/disable the compiling of your files.

cwd

default: "src"

The current working directory.

dest

default: "app"

Output directory.

devServer.start

default: false

Set to true if you want to use the provided development server.

devServer.express

default: null

You can pass your own express instance.

devServer.port

default: 3000

Change the port of the development server.

exportData

default : false

Export the complete data stack as JSON file.

ext

default: ".html"

Define the extension of your output files.

flatten

default: false

Flatten your output directory.

helpers

default: ["helpers/*.js"]
relative to cwd

types (object)

There are 4 necessary types which needs to be defined:

layouts
pages
partials
data

Each type has the following options:

types[type].createDeepIds

For every type you can create deep ids. The whole path to the file will be used. That makes it possible to have multiple identical named data, partial, layout and page files in different folders.

types[type].dir

default: "[type]"
relative to cwd

You can change the type directory to any folder you like.

Important: for every type directory Mangony creates a watcher if options.watch is true.

types[type].files

default: ["**/*.[typeExtension]"]

Pass an array of files to the files property. Globbing is possible.

types[type].pathDelimiter

default: "/"

By using deep ids the id is the path to your file. But using such ids in handlebars is not possible for your data files. That`s why you can define a path delimiter.

watch

default: false

Just enable the internal watching of file changes.

Why Mangony?

Static site generator and server?

In general I love static site generators. Simply deploy the output and you`re done - great.

But there is one major problem. When developing every change leads to the compiling of all pages. In large projects this is very time consuming.

So why not just combine a server for development purpose with a static site generator?

Special thanks goes to Henri Podolski for the idea and discussion.

Assemble?

For 2 1/2 years I am working with Assemble. It is a great tool and I like it a lot.

The new Assemble (a full stack site generator) seems to be pretty nice, but it doesn`t fit so well in my current stack. Grunt-assemble however has a major bug, so it is not usable in the latest release.

Last but not least

I just wanted to develop a static site generator.

Roadmap

>=2.0.0

When necessary an eco system for plugins will be integrated.

License

see LICENSE.md.