entu-ssg

Entu Static Site Generator

Benefits

• Simple Pug (former Jade), Markdown, Yaml static site generator.
• Generate static HTML files from Pug templates or Markdown.
• Pass data to templates with Yaml files.
• Use locale identificator in filenames to generate locale specific content and paths.
• Generate site CSS from Stylus files.
• Use Your favorite tools/editors.
• Host it on Your own server, on Netlify, on S3, on ...

Installation and usage

NPM is the recommended installation method. To install Entu SSG run:

$ npm install entu-ssg

To build Your site run:

$ npx entu-ssg build /path-to-my-page/entu-ssg-config.yaml

If source folder is Git repository Entu SSG runs incremental build (based on Git changes since last commit). To run full build use full as second parameter:

$ npx entu-ssg build /path-to-my-page/entu-ssg-config.yaml full

Local development

MacOS and Windows GUI for local development are downloadable from github.com/entu/ssg-app. Or run (for full build use full as second parameter):

$ npx entu-ssg serve /path-to-my-page/entu-ssg-config.yaml

Configuration

Sites build process is configurable by Yaml file and its path must be first argument for entu-ssg.js. Required parameters are:

• locales - List of locale folders to generate. You can put locale identificator to filename (like index.en.pug or data.et.yaml) for locale specific content.
• defaultLocale - If set, page paths in this locale will not get locale prefix (/en/about will be just /about).
• source - Folder with source files (realtive to build config.yaml). If not set uses src folder.
• js - Folder with source JavaScript files (realtive to build config.yaml). Files will be combined to script.js file in build folder.
• styl - Folder with Stylus files (realtive to build config.yaml). Files will be converted and combined to style.css file in build folder.
• build - Folder to put generated HTML (realtive to build config.yaml). If not set uses dist folder.
• assets - DEPRECATED in v5.6! Folder with static assets (JS, images, ...).
• protectedFromCleanup - List of paths what is not deleted if build.sh is ran with cleanup parameter. Relative to build path.
• server.port - What port to use for serving on localhost.
• server.assets - DEPRECATED in v5.6! Serving page in localhost will map this url to folder specified in assets parameter.
• server.public - Serving page in localhost will serve content of this folder from / path. If not set uses public folder. NB! On build/deploy You must copy files in this folder to build folder.
• dev.aliases - Build pages aliases.
• dev.paths - List of (source) paths to build. Relative to source path.
• dev.ignorePaths - List of (source) paths to ignore on build. Relative to source path.

Example build configuration file:

locales:
  - en
  - et
defaultLocale: et

source: ./src
js: ./src/_scripts
styl: ./src/_styles
build: ./dist

server:
  port: 4000
  public: ./public

dev:
  aliases: true
  paths:
    - test/page1
    - test/page2
  ignorePaths:
    - test/page3

Page template and content

Page template - index.pug

Page is generated from index.pug file. All other .pug files are ignored, but You can use those files for include/extends. You can put locale identificator to filename (like index.en.pug) for locale specific content.

Page content - data.yaml

To pass content and configuration to index.pug use data.yaml file. This data is passed to index.pug in object named self (To get property text from data.yaml use self.text in index.pug).

You can put locale identificator to filename (like data.en.yaml) for locale specific content. This way You can use index.pug as a template and pass all locale specific texts from "data" files.

Some page parameters will change how HTML is generated. Those are:

• disabled - If true, page will not be generated nor loaded to self.otherLocalePaths object.
• path - If set, it will override folder based path.
• aliases - List of path aliases. Will make redirekt urls to original path.
• data - Files to load data from. This data is passed to index.pug in object named self.data. You can use relative path (./ or ../). If used, it's relative to data.yaml file. Root (/) path is Your source folder (set in config.yaml).

Some additional parameters are passed to template in self object. Those are:

• locale - Page's locale.
• defaultLocale - Default locale from config Yaml file.
• path - Page's path. If alias is generated, then this is page's path and not alias.
• alias - Returns true if page is alias.
• otherLocalePaths - Object of links to same page in other locales.
• md - Function to render Markdown. Expects string as input.
• env - Object of environment parameters.

Example page data.yaml:

path: /testpage1
aliases:
  - /test
  - /test123
data:
  news: ./datafiles/news.yaml
someOtherData:
  - A
  - B

Multipage content

To use same template for multiple pages (blog posts for example) you can put array of objects into data.yaml file. Each object must describe page as explained above.

If You need to use keys do distinct each page there is option to use object in data.yaml file with parameter multipage: true. In this case You can use page path as key.

Example multipage data.yaml as array:

-
  path: /testpage1
  someOtherData:
    - A
    - B
-
  path: /testpage2
  someOtherData:
    - C
    - D

Example multipage data.yaml as object:

multipage: true
page1:
  path: /testpage1
  someOtherData:
    - A
    - B
page2:
  path: /testpage2
  someOtherData:
    - C
    - D

Global content - global.yaml

To pass same content to all index.pug files use global.yaml file. This data is passed to index.pug in object named self (To get property footer from global.yaml use self.footer in index.pug). Data what is set in pages's own data.yaml will expand/overwrite global.yaml.

You can put locale identificator to filename (like global.en.yaml) for locale specific content.

Page CSS and JS

Page inline style - style.styl

For inserting inline CSS to individual pages use style.styl file in page's folder. Generated style is inserted just before </head> tag.

You can put locale identificator to filename (like style.en.styl) for locale specific style.

Page inline scripts - script.js

For inserting inline JS to individual pages use .js file in page's folder. Generated script is inserted just before </body> tag.

You can put locale identificator to filename (like script.en.js) for locale specific script.

On build ...

... source folder like this ...

- src
    |- _scripts
    |   |- somescript.js
    |   +- somescript2.js
    |
    |- _styles
    |   +- style.styl
    |
    |- _templates
    |   |- layout.pug
    |   +- mixins.pug
    |
    |- testpage1
    |   |- data.en.yaml
    |   |- data.et.yaml
    |   +- index.pug
    |
    |- testpage2
    |   |- data.yaml
    |   |- index.en.pug
    |   |- index.et.pug
    |   |- style.styl
    |   |
    |   +- testpage2en
    |       |- data.en.yaml
    |       |- index.en.pug
    |       +- script.en.js
    |
    |- data.yaml
    |- global.yaml
    +- index.pug

... will be converted to build folder like this

- dist
    |- en
    |   |- index.html
    |   |- testpage1
    |   |   +- index.html
    |   |
    |   +- testpage2
    |       |- index.html
    |       +- testpage2en
    |           +- index.html
    |
    |- et
    |   |- index.html
    |   |- testpage1
    |   |   +- index.html
    |   |
    |   +- testpage2
    |       +- index.html
    |
    |- script.js
    |- script.js.map
    |- style.css
    +- style.css.map