@the-noah/static-site-generator

Static Site Generator

Generate an optimized static website, or use at run-time with a custom server.

Table of Contents

• Static Site Generator
  • Table of Contents
  • Features
• Documentation
  • Installation
    • Global
    • Project
  • Configuration (optional)
  • Command-Line Interface (CLI)
  • Library
    • Importing
    • async build()
    • async renderPage(pagePath, data)
    • async getData()
  • Page Templates
  • Understanding How Data is Collected and Used
    • CSS & SASS
    • JavaScript & TypeScript
    • JSON
    • YAML
  • Examples
    • Express Server

Features

1. Compiles and optimizes SCSS files.
2. Optimizes JavaScript.
3. Compiles TypeScript to JavaScript.
4. Embed data from JSON and YAML files.
5. HTML templates with ejs and moe.
6. Automatically copies static files.
7. Can be used with a custom web server.

Documentation

Installation

Global

Install with: npm install -g @the-noah/static-site-generator

Project

Install with npm install -s @the-noah/static-site-generator.

Add static-site-generator as a script in your package.json to build your website.

Configuration (optional)

The configuration file must be named .static-site-generator.config.json and must be in the root of your project. Configuration is available in options.

Property	Type	Default	Description
srcDir	string	"src"	Path to look in for files.
buildDir	string	"build"	Path to save final files to.
staticDir	string	"static"	Path in srcDir to look for static files.
logLevel	number	0	0 = all, 1 = no info, 2 = no sucess, 3 = no warning, 4 = no error - each level also inherits from the last
compressionLevel	Number	2	How much to compress files - 0 = none, 3 = max

Command-Line Interface (CLI)

Run static-site-generator in the root of your project to build your website.

Library

static-site-generator can be used as a library, such as with a web server.

Importing

JavaScript

const {staticSiteGenerator} = require("@the-noah/static-site-generator");

TypeScript

import {staticSiteGenerator} from "@the-noah/static-site-generator";

async build()

Renders all pages in options.srcDir and saves them in options.buildDir, as well as copies all files from options.srcDir/options.staticDir to options.buildDir.

Returns Promise<void>

Example

await staticSiteGenerator.build();

async renderPage(pagePath, data)

Renders the page found at pagePath with the data data and returns a Promise<string> containing the minified HTML.

Returns Promise<string>

Property	Type	Description
pagePath	string	Path of the page to render.
data	Record<string, unknown>	Data used to render the page.

Example

const html = await staticSiteGenerator.renderPage("index.ejs", {message: "Hello, World!"});

async getData()

Returns all data from files found in options.srcDir.

Returns Promise<Record<string, unknown>>

Example

console.log(await staticSiteGenerator.getData());

Page Templates

The following template engines are built-in.

• ejs
• moe

You can easily add your own using the addPageFile and addPageHandler methods.

Understanding How Data is Collected and Used

The getData() function retrieves data from different files types and mashes it together.

CSS & SASS

.css and compiled .scss files will be compressed and available as a string under their filename in the css object.

Example

main.css will be compressed then be available under css.main.

style.scss will be compiled and compressed then available under css.style.

/* main.css */
h1{
  color: red;
}

console.log(data.css.main === "h1{color:red}"); // true

JavaScript & TypeScript

.js and compiled .ts files will be compressed and available as a string under their filename in the js object.

Example

app.js will be compressed then available under js.app.

script.ts will be compiled and compressed then available under js.script.

// app.js
alert("Hello, World!");

console.log(data.js.app === "alert(\"Hello, World!\");"); // true

JSON

.json files will be available under their filename.

Example

blog.json will be available under blog.

[
  {
    "title": "My New Blog",
    "date": "2020-5-6",
    "text": "This is my new blog where I talk about cats!"
  }
]

console.log(data.blog[0].date !== "2020-5-6") // true

YAML

.yaml and .yml files will be available under their filename.

Example

test.yml will be available under yml.

message: "hello"

console.log(data.test.message === "hello"); // true

Examples

Express Server

const path = require("path");

const {staticSiteGenerator} = require("@the-noah/static-site-generator");
const express = require("express");

const app = express();
const PORT = 3000;

app.get("/", async (req, res) => {
  res.send(await staticSiteGenerator.renderPage(path.join(staticSiteGenerator.options.srcDir, "index.ejs"), await staticSiteGenerator.getData());
});

app.listen(PORT, () => console.log(`Server running at http://localhost:${PORT}`));