@devnetic/static-site-generator

Static Site Generator

This package let you create a static site in a very easy and fast way, you can use markdown files to create the content, and create themes to render the content.

The themes use handlebars to render the data coming from the markdown files, this template system is easy to use but powerful enough to almost every necessary task, but in case that you need extra features, you can write your own addons or helpers for handlebars.

To do this, add your new helpers in the ./template-systems/register.js. Below you can see how a new helper would be registered:

const templateSystem = require('./template/templateSystem')

const handlebars = templateSystem.getSystem('handlebars').system

handlebars.registerHelper('loud', (value) => {
    return value.toUpperCase()
})

Another option is to implement and/or register a totally new template systems like EJS for example. To do this you only need to follow the necessary conventions that the generator expects:

Create a new file in the ./template-system directory with the following code (this example use EJS, but should the same for other template systems):

// Import the NPM package for the template template engine
const ejs = require('ejs')

/**
 * Compile the template and return the compiled result.
 *
 * @param {string} template
 * @param {object|Array} data
 * @return {string}
 */
const compile = (template, data) => {
  return ejs.render(template, data)
}

/**
 * Export the EJS template system.
 *
 * @return {object}
 */
const template = () => {
  return {
    name: 'ejs',  // Required: this is the name to setup in the config file
    system: ejs,  // Required: this is necessary for possible extensions
    compile       // Required: this function is called by the generator
  }
}

module.exports = {
  template
}

The compile and template function signature must always be the same. Now you need to setup the generator to use your new template system, to do this, modify the config.json file:

{
  ...,
  "templateSystem": "ejs",
  ...,
}

Usage

After you install the package you will have access to a new command called ssg, this command will et you interact will all the optiona avaialables, like create a new site, run the build process for new added content, etc.

Using the -h or --help modifier you can get all the available options:

$ ssg -h | ssg --help

Usage: ssg <option> [modifier]

Options:
  -b, --build           Run the build process
  -c, --clean           Clean the build directory
  -n, --new             Generate a new site
  -v, --version         Display version
  -w, --watch           Run the build process watching changes
  -h, --help            Show this help


Copyright 2021 - Static Site Generator

The -n, --new will create the necessary directories and a config file with some initial values to run your new site.

A typical config file will have the next structure:

{
  "data": {
    "path": "content",
    "files": [
      ".md",
      ".html",
      ".mdx"
    ]
  },
  "build": "docs",
  "theme": "default",
  "paginate": 5,
  "templateSystem": "handlebars",
  "assets": [
    ".css",
    ".js",
    ".gif",
    ...,
    ".wma",
    ".aac"
  ],
  "site": {
    "title": "Your site tytle",
    "author": "Your name"
  }
}

• data.path (string): The content path.
• data.files (string[]): The files to be includes like content for the site.
• build (string): The path where the build is created.
• theme (string): The theme used to build the site.
• paginate (number): Define the number of recod per page when pagination is used.
• templateSystem (string): The template system used in the theme files.
• assets (Array[string]): Define the assets types inside the theme directory.
• site.title (string): The site title.
• site.author (string): The site author name.