site

README

Site

A simple static site builder

Example site
This is the recommended place to start if you just want to get going.

Install

Make sure you have go installed.

go install github.com/tomboddaert/site@latest

Use

The basic commands are here.

The file structure should look like this:

.
├── out/                 - the built output
│   └── ...
├── pages/               - the templated pages
│   ├── <template name>/
│   │   └── ...
│   └── ...
├── raw/                 - the non-templated pages
│   └── ...
├── templates/           - the templates
│   ├── <single file
│   │    template name>
│   ├── <multi file
│   │    template name>/
│   │   └── ...
│   └── ...
├── data.json            - page variables
|    (optional)
├── siteConfig.json      - configuration
|    (optional)
└── tsconfig.json        - TypeScript configuration
     (optional)

siteConfig.json

This file sets the config for site. The default config (do not use comments):

{
  "TemplateDir":      "templates", // Sets the template directory
  "TemplateRootFile": "root.json", // Sets the root file of templates
  "TemplatedSrcDir":  "pages",     // Sets the templated page directory
  "RawSrcDir":        "raw",       // Sets the raw directory
  "DstDir":           "out",       // Sets the output directory
  "DstMode":          "0755",      // Sets the file permissions for the output (octal)
  "DataFile":         "data.json", // Sets the file data is read from
  "FmtTemplatedHtml": false,       // Formats templated html files
  "FmtRawHtml":       false,       // Formats raw html files
  "ExcludePaths":     [],          // Regular expressions that match paths to ignore
  "PrebuildCmds":     [],          // Commands to run before building
  "PostbuildCmds":    [],          // Commands to run after building

  "NotFoundPath":     "404"        // 404 page (serve)
}

out

This is the default output directory, where the built pages will be.

templates

This is the directory for templates; templates can either be a single file or a directory of files, which will be concatenated into one template. The name of the file or directory is the template name.

The templates use Go templating with sprig functions. Official documentation; Nomad Tutorial.

pages

This is the directory for pages that need templating. The pages should be in a subdirectory with the same name as the template.

rawPages

This is the directory for files that do not need templating.

data.json

This file is for variables used in the templates. The root should be an object, where the keys are the paths of the page in pages, and the values are the data to be used in the page.
There can also be a default key, whose corresponding values are used when not overridden.
Defaults for a template can be set with a key corresponding to the name of the template, these take priority over the standard default.

tsconfig.json

If TypeScript is used, this file is needed. The settings below need to be set. This will need to be adjusted if directory names are changed in siteConfig.json.

{
  "compilerOptions": {
    "rootDir": "./raw",
    "outDir": "./out",
  },
  "include": [ "./raw" ]
}

The file can generated with:

npx tsc --init

outFile could be used to transpile a separate directory of TypeScript to one file of JavaScript. See the tsconfig docs for more information.
rootDir and include could be changed to separate TypeScript from the pages.
outDir could be changed if you want to use the output JavaScript in a template.

Using the tool

Help:

site help

Building:

site build

Serving:

site serve

Serving on a different address:

Linux:

SITE_ADDRESS=127.4.0.1:80 site serve

Windows cmd:

set SITE_ADDRESS=127.4.0.1:80
site serve

PowerShell:

$Env:SITE_ADDRESS = "127.4.0.1:80"
site serve

Build and serve:

site build serve

Building TypeScript

Adding TypeScript building to your site is easy, just add the following to the siteConfig.json file:

{
  "ExcludePaths": ["\\.m?ts$"],
  "PostbuildCmds": [
    ["npx", "tsc"]
  ]
}

License

You maintain all rights to any work you create using the build functionality of this tool, and attribution is not required in the created work.

Licensed under the MIT License (source) or Apache License, Version 2.0 (source) at your option.