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
andallow.YFMContextData
inoptions
. - 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 yourpartial
orpage
. - Add a
README.md
file next to yourpartial
orpage
.
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
Register custom handlebars helpers by providing the path. Globbing is possible.
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.