Usage

Setup

Kiss is an object so will need to be instantiated. In its simplest form kiss will scan your pages directory and use file based routing to generate the html output.

const Kiss = require('kiss-ssg')
    const kiss = new Kiss()
    kiss.scan()
    kiss.generate()
    

Note: kiss will generate the default folders for you when you first run the script. You can overwrite the folder locations bay passing a config to the kiss constructor.

The default config options are:

{
      dev: false,
      verbose: false,
      cleanBuild: true,
      folders: {
        src: './src',
        build: './public',
        assets: './src/assets',
        layouts: './src/layouts',
        pages: './src/pages',
        partials: './src/partials',
        models: './src/models',
        controllers: './src/controllers'
      }
    }
    

Partials: Cam be a .hbs, a .html file or a .md file, Note: .md files are automatically parsed

Option Default Purpose
dev false Dev mode will start a local live-reload server and rebuild on file change.
verbose false Enables additional output on the terminal, when set to true
cleanBuild true Removed all files from the build dir before generating.
folders see above A JSON object of alternative folder locations


Note: All config settings are available in the view under "this.config"

Assets

Any static files you have in the assets directory will be copied to the build directory


Methods

kiss-ssg has 3 methods

  • .page()
  • .pages()
  • .scan()

The simplest usage is to use .scan() to scan your 'pages directory' for *.hbs files and outputs them to the 'build folder'.

.page()

Instead (in in conjunction) of using the .scan() method you can pass a model to the view using the .page() method. This allows you to name the view and pass a model to that view. The model is then available in the handlebar template under the model property, e.g.

const Kiss = require('kiss-ssg')
    const kiss = new Kiss({ dev: true })
    kiss
      .page({
        view: 'index.hbs',
        model: 'index.json',
        controller: 'index.js',
        title: 'My Page Title',
      })
      .generate()
    

Note: The file locations of the models, views, and controllers are relative to the folder locations defined in the kiss configuration. Alternatively, instead of passing a file location you can pass a native object for that setting.

Views: can se a .hbs file or a string Models: can be a .json file, a http api endpoint, or a JSON object Controllers: can be a .js file or a function that returns a page option JSON to be merged into the page options

The options that you can pass to .page() & pages() are:

  {
        view: 'index.hbs',
        model: {}
        controller: ({model})=>{return {model: model}},
        title: 'Page Title',
        description: 'A description of the page (useful for meta data)'
        path: '/',
        slug: 'index',
      }
    

These options are both used internally by kiss and are available in view.

  • view = A handlebars view.
  • model = A json object, the name of the json file relative to the models folder or a URL for an API endpoint.
  • controller = A function that returns a page options object - used for manipulating data in the model.
  • title = The page title
  • path = the folder path to the page
  • slug = the name of the file without the extension

page and path create the url, i.e. /{path}/{slug}.html

Note: If you don't pass a path or a slug they will be inferred from the view

.pages()

In addition to passing page options you can also pass a option mapper to act as a controllers to the .page() and .pages() methods:

const Kiss = require('kiss-ssg')
    
    const kiss = new Kiss()
    kiss
      .page({
        title: 'My Team Page',
        view: 'about/index.hbs',
        model: 'departments.json',
        controller: ({ model }) => {
          return {
            model: model.sort(
              (a, b) => parseInt(a.sort_order) - parseInt(b.sort_order)
            ),
          }
        },
      })
      .generate()
    

Controllers

The option mapper is really useful for mapping a slug from the model. This is great for dynamic slugs and a necessity when passing an array of models to the .pages() method to generate a series of pages.

const Kiss = require('kiss-ssg')
    const kiss = new Kiss({ test: '123' })
    
    kiss
      .page({
        title: 'Page Title',
        view: 'index.hbs',
      })
      .pages({
        view: 'course.hbs',
        model: 'https://{my-cool-api}/courses',
        controller: ({ model }) => {
          return {
            slug: model.slug,
          }
        },
        path: 'courses',
      })
      .generate()
    

Helpers

Kiss-ssg registers a few useful helpers by default including a markdown parser.

Kiss exposes the handlebars object so you can register your own helpers, e.g.

//  Extending handlebars
    kiss.handlebars.registerHelper('stringify', function (obj) {
      return JSON.stringify(obj, null, 3)
    })