![\"Logo](\"https://github.com/Sebastian-Fitzner/mangony/blob/master/logo.svg\"){kind=logo}
\n\n\n ![\"NPM](\"https://badge.fury.io/js/mangony.svg\"){kind=icon}
\n\t![\"Build](\"https://travis-ci.org/Sebastian-Fitzner/mangony.svg\")
\n\t![\"NPM](\"https://nodei.co/npm/mangony.png?mini=true\")
\n\t![\"license\"](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n
Yet another static site generator - fast, simple, powerful and pluggable.
\n\nMangony fulfills just one task: It takes files, saves them in cache, use templates and compiles them to an output directory.
\n\n## Features\n\n1. Mangony can be used anywhere as npm module. \n2. By using the provided development server ([express](https://github.com/expressjs/express)) every change is completed in no time, no matter how many pages you have in your project.\n3. Only changed pages get compiled. \n4. Creation of deep ids is possible for all types. \n5. For every type (data, partials, layouts, pages) Mangony adds a watcher ([chokidar](https://github.com/paulmillr/chokidar)).\n6. [HJSON](https://github.com/laktak/hjson) is available.\n7. Supports different template rendering options like [Handlebars](https://github.com/wycats/handlebars.js/) or [React](https://github.com//).\n\n## Installation\n\nInstall Mangony with \n\n``` bash\nnpm install mangony --save-dev\n```\n\nFor the installation of the Grunt plugin, see [grunt-mangony](https://github.com/Sebastian-Fitzner/grunt-mangony).\n\n## Usage\n\nJust create a new instance of Mangony: \n\n``` js\nimport Mangony from 'mangony';\nconst app = new Mangony();\n```\n\nThen render your mangony instance:\n\n``` js\napp.render();\n```\n\nTo render files with a template engine you need to add a plugin. There are some engines provided to you, but you can easily create your own if you want to.\nLet's go with JSX for now: \n\n``` js \nimport Mangony from 'mangony';\nimport jsxTemplaterPlugin from 'mangony/plugins/jsx-templater.js';\n\nconst app = new Mangony();\n\napp.render()\n .then(() => app.use(jsxTemplaterPlugin);\n```\n\nWhen using the default options your files get compiled. But you can also integrate the development server. \n\n## Examples\n\n**dev.js**\n\nLet`s say we want to develop a new static page with the dev server in place. \n\n``` js\nimport Mangony from 'mangony';\nimport jsxTemplaterPlugin from 'mangony/plugins/jsx-templater.js';\nimport serverPlugin from 'mangony/plugins/server.js';\n\nconst app = new Mangony({\n cwd: `src`,\n dest: `dist/`,\n watch: true,\n types: {\n data: {\n dir: 'data',\n files: [\n '**/*.json',\n '**/*.hjson'\n ]\n },\n partials: {\n dir: 'partials',\n files: [\n '**/*.hbs'\n ]\n },\n pages: {\n dir: 'pages',\n files: [\n '**/*.tsx'\n ]\n },\n layouts: {\n dir: 'layouts',\n files: [\n '**/*.hbs'\n ]\n }\n }\n});\n\napp.render()\n .then(() => app.use(jsxTemplaterPlugin, {\n compileStaticFiles: false\n })\n .then(() => app.use(serverPlugin, {\n bsEnabled: true,\n injectScript: true,\n start: true,\n port: 3000,\n usePort: true,\n useAssetsDir: false,\n }));\n```\n\nWhen using the `devServer` options all routes get registered.\n\nNow you can open your browser at `localhost:3000` and navigate to the page you want to change. \nThe url is the path to your page without a file extension (i.e. `/index`). If you want to use the file extension as well, just enable it via options.\n\n**prod.js**\n\nLet`s say we want to build our static page. \n\n``` js\nimport Mangony from 'mangony';\nimport jsxTemplaterPlugin from 'mangony/plugins/jsx-templater.js';\n\nconst app = new Mangony({\n cwd: `src`,\n dest: `dist/`\n types: {\n data: {\n dir: 'data',\n files: [\n '**/*.json',\n '**/*.hjson'\n ]\n },\n partials: {\n dir: 'partials',\n files: [\n '**/*.hbs'\n ]\n },\n pages: {\n dir: 'pages',\n files: [\n '**/*.hbs',\n '**/*.md'\n ]\n },\n layouts: {\n dir: 'layouts',\n files: [\n '**/*.hbs'\n ]\n }\n }\n});\n\napp.render()\n .then(() => app.use(jsxTemplaterPlugin, {\n compileStaticFiles: true,\n }));\n```\n\nNow you can find the complete rendered output in the destination folder.\n\n## Options\n\n### Generic Options\n\n#### assets\n\n- default: `\"./\"`\n\nPath to your assets in your destination directory.\n\n#### collections\n\n- default: `[]`\n\nAdd your own collections which can be used in YAML front matter or `filename.settings.hjson`.\n\n#### cwd\n\n- default: `\"src\"`\n\nThe current working directory.\n\n#### debug\n\n- default: `false`\n\nPrint more comments in your terminal to debug a bit better ;).\n\n#### dest\n\n- default: `\"app\"`\n\nOutput directory.\n\n### exportData\n\n- default : `false`\n\nExport the complete data stack as JSON file.\n\n### ext\n\n- default: `\".html\"`\n\nDefine the extension of your output files.\nThis can be overridden per file by using `YAML Front Matter` or `page.settings.json`.\n\n### flatten\n\n- default: `false`\n\nFlatten your output directory.\n\n### types (object)\n\nThere are 4 necessary types which needs to be defined:\n\n- layouts\n- pages\n- partials\n- data\n\nEach type has the following options:\n\n### types[type].createDeepIds\n\nFor 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.\n\n### types[type].dir\n\n- default: `\"[type]\"`\n- relative to `cwd`\n\nYou can change the type directory to any folder you like.\n\n**Important: for every type directory Mangony creates a watcher if `options.watch` is `true`.**\n\n### types[type].files\n\n- default: `[\"**/*.[typeExtension]\"]`\n\nPass an array of files to the files property. Globbing is possible.\n\n### types[type].pathDelimiter\n\n- default: `\"/\"`\n\nBy 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.\n\n### watch\n\n- default: `false`\n\nJust enable the internal watching of file changes.\n\n## Plugins \n\n### Dev Server Plugin (`mangony/plugins/server.js`)\n\nThe dev server is providing the best developer experience by triggering a reload when a file has changed and supporting the rendering of only requested files. \nThat means, even when your project is growing in terms of pages and components it almost does not matter because only changed files get recompiled and rendered. \n\nWhen the server is registered, it sets `servermode` in your `root` context to `true`. This is helpful if you want to distinguish between static or server related executions. \n\n#### Options\n\n##### devServer.bs\n\n- default: `null`\n\nYou can pass your own Browser-Sync instance.\n\n##### devServer.bsEnabled\n\n- default: `true`\n\nYou can disable browser-sync.\n\n##### devServer.bsOptions\n\n- default: `null`\n\nYou can pass your custom [Browser-Sync options](https://www.browsersync.io/docs/options) object.\n\n##### devServer.express\n\n- default: `null`\n\nYou can pass your own express instance.\n\n##### devServer.injectScript\n\n- default: true\n\nSet to `false` if you want to disable the injection of the browser-sync script.\n\n##### devServer.port\n\n- default: `3000`\n\nChange the port of the development server.\n\n##### devServer.start\n\n- default: `false`\n\nSet to `true` if you want to use the provided development server.\n\n##### devServer.useExt\n\n- default: `true`\n\nSet to `false` if you do not want to use extensions in your routes.\n\n##### devServer.usePort\n\n- default: `true`\n\nSet to `false` if you have already a port provided to express.\n\n##### devServer.useAssetsDir\n\n- default: `true`\n\nSet to `false` if you have already an asset directory provided to express.\n\n### JSX Templater Plugin (`mangony/plugins/jsx-templater.js`)\n\nWith this plugin we can render React, Preact or similar JSX capable projects. Mangony is using a temporary directory to compile your files with ESBuild. \nThat means `.tsx` and `.jsx` files are both supported out-of-the-box. \n\n#### Options\n\n##### compileStaticFiles\n\n- default: `true`\n\nEnable/disable the compiling of your files.\n\n### Handlebars Templater Plugin (`mangony/plugins/jsx-templater.js`)\n\n#### allow.YFMLayout (`Boolean`)\n\n- default: `false`\n\nAdd the possibility to reference layouts in YAML front matter. `{{{yield}}}` will be replaced in your referenced layout with the content of the page.\n\n#### allow.YFMContextData (`Boolean`)\n\n- default: `false`\n\nFlag to add a specific data context for your page by referencing a data file id in YAML front matter.\n\n#### compileStaticFiles\n\n- default: `true`\n\nEnable/disable the compiling of your files.\n\n#### handlebarsInstance\n\n- default: Handlebars\n\nAdd the possibility to pass your own instance with custom helpers, like: \n\n```js\nimport Mangony from 'mangony';\nimport hbsTemplaterPlugin from 'mangony/plugins/hbs-templater.js';\nimport serverPlugin from 'mangony/plugins/server.js';\nimport mgyHelperWrapWith from 'mangony-hbs-helper-wrap-with';\nimport mgyHelpers from 'mangony-hbs-helpers';\nimport layouts from 'handlebars-layouts';\nimport handlebarsHelpers from 'handlebars-helpers';\nimport handlebars from 'handlebars';\nimport * as helpers from './helpers/hbs-helpers.js';\n\nconst engine = handlebars.create();\n\nhandlebarsHelpers({ handlebars: engine });\nlayouts.register(engine);\nmgyHelpers.register(engine);\nmgyHelperWrapWith.register(engine);\nhelpers.register(engine);\n\nconst mangony = new Mangony({\n cwd: 'src',\n dest: 'dist',\n exportData: false,\n evtNamespace: 'Mangony',\n ext: '.html',\n flatten: false,\n collections: [\n 'sitemap',\n ],\n types: {\n data: {\n dir: 'templates',\n files: [\n '**/*.json',\n '**/*.hjson',\n ],\n },\n pages: {\n dir: 'templates/pages',\n files: [\n '**/*.hbs',\n '**/*.md',\n ],\n },\n partials: {\n dir: 'templates/partials',\n files: [\n '**/*.hbs',\n ],\n },\n layouts: {\n dir: 'templates/layouts',\n files: [\n '**/*.hbs',\n ],\n },\n },\n watch: devMode\n});\n\nmangony.render()\n .then(() => {\n return mangony.use(hbsTemplaterPlugin, {\n handlebarsInstance: engine,\n allow: {\n YFMContextData: true,\n YFMLayout: true,\n },\n compileStaticFiles: false,\n });\n })\n .then((templater) => {\n templater.then(() => {\n return mangony.templater.renderPages();\n });\n })\n\n```\n\n## Why Mangony?\n\n**Static site generator and server?**\n\nIn general I love static site generators. Simply deploy the output and you`re done - great. \n\nBut there is one major problem. When developing, every change leads to the compiling of all pages. In large projects this is very time consuming.\n\nSo why not just combine a server for development purpose with a static site generator?\n\n## Test\n\nJust checkout the repository, install all dependencies with `npm install` and execute `npm test`. \n\n## Examples \n\nSee `examples` folder for JSX, Handlebars or Freemarker Templates. \n\n## License \n\nsee [LICENSE.md](https://github.com/Sebastian-Fitzner/mangony/blob/master/LICENSE.md).\n","readmeFilename":"README.md","users":{"sebastian-fitzner":true}}