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

1. Download latest build

2. Run:

   $ npm run 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:

   $ npm run 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):

$ npm run 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 speciffic 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).
• 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).
• assets - 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 - Serving page in localhost will map this url to folder specified in assets parameter.
• 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
source: ./source
js: ./source/_scripts
styl: ./source/_styles
build: ./build
assets: ./assets
protectedFromCleanup:
  - assets
  - index.html
server:
  port: 4000
  assets: /assets/
dev:
  aliases: true
  paths:
    - test/page1
    - test/page2
  ignorePaths:
    - test/page3

Content

Page content - index.pug

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

Page data and configuration - data.yaml

To pass data 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 speciffic content.

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).

Example page data.yaml:

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

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 speciffic 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 speciffic script.

On build ...

... source folder like this ...

- source
    |- _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

- build
    |- 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