Tools / Static site generator

Gengo

Markdown, HTML templates and one YAML manifest in, a static site out. A single Go binary with nothing else to install. This website is built with it.

Install

The install script downloads the latest release for your platform, checks it against the published checksums and puts gengo in ~/.local/bin.

$ curl -fsSL https://raw.githubusercontent.com/saasuke-labs/gengo/main/install/install.sh | bash

To pin a version:

$ curl -fsSL https://raw.githubusercontent.com/saasuke-labs/gengo/main/install/install.sh | VERSION=0.0.15 bash

You can also download an archive from the releases page, or build from source:

$ git clone https://github.com/saasuke-labs/gengo
$ cd gengo
$ go build -o gengo ./cmd/main.go

Quick start

A Gengo site is a manifest plus the files it points to. Create gengo.yaml:

title: My Site

default-layout-template: layouts/layout.html
home-template: layouts/home.html

static-assets:
  - path: static
    destination: static

sections:
  blog:
    pages:
      - title: "Hello world"
        markdown-path: posts/hello-world.md

The layout wraps every page. It is a Go html/template file:

<!DOCTYPE html>
<html lang="en">
  <head>
    <title>{{ .Title }}</title>
  </head>
  <body>
    {{ .HTML }}
  </body>
</html>

Build the site, then preview it:

$ gengo generate --output dist
$ gengo serve --site dist --watch

The page above is written to dist/blog/hello-world.html: one folder per section, one file per page.

The manifest

Everything Gengo builds is declared in gengo.yaml.

KeyWhat it does
titleSite title, available to templates.
default-layout-templateThe HTML shell wrapped around every page.
home-templateTemplate for the home page, written to index.html.
default-page-templateTemplate that wraps the rendered content of a page inside the layout.
default-section-templateTemplate for a section's index, which lists its pages.
static-assetsFolders copied as they are. Each entry has a path and a destination; use destination: . for files that belong at the site root.
sectionsNamed groups of pages. The section name becomes the folder in the output.
sourcesHTTP services pages can read at build time. See build-time data.

Pages

Each entry under a section's pages accepts:

KeyWhat it does
markdown-pathThe source file. Markdown is rendered; an .html file is inserted as it is.
titlePage title.
descriptionShort description for listings and meta tags.
published-at, last-edited-atDates you can show or sort by in templates.
tagsA list of tags.
metadataFree-form key/value pairs for your templates.
dataWhich sources to fetch for this page.

The same keys can go in front matter at the top of the Markdown file instead of the manifest.

Templates

Templates use Go's html/template syntax. The layout receives:

FieldContains
.TitleThe page title.
.SectionThe section name, empty on the home page.
.MetadataThe page's metadata map. Read a key with {{ index .Metadata "key" }}.
.HTMLThe rendered page content.
.DataBuild-time data fetched for the page.

Commands

gengo generate

Builds the site from the manifest.

FlagDefaultWhat it does
--manifestgengo.yamlPath to the manifest. Can be repeated.
--outputoutputOutput directory.
--plainoffPlain log output instead of the terminal UI. Use it in CI.
--watchoffRebuild on change, with hot reload.

gengo serve

Serves a generated site locally.

FlagDefaultWhat it does
--sitesiteDirectory to serve.
--watchoffWatch mode with hot reload.

gengo version

Prints the installed version.

Diagrams and charts

A fenced code block with the language nagare is rendered to an inline SVG by Nagare, so diagrams live in the Markdown next to the text they explain.

```nagare
web:Browser(text: "Shop")
api:Server(title: "API", port: 8080)

web.e --> api.w
```

If a block fails to render, the error is shown in the page where the diagram would be, so it is hard to miss before you publish.

Build-time data

Pages can pull data from any HTTP service while the site builds: a comments service such as Kotomi, a weather API, your own backend. Declare the service once under sources:

sources:
  comments:
    # Go template, rendered per page with that page's metadata
    url: https://comments.example.com/pages/{{ index .Metadata "page-id" }}/comments
    headers:
      Accept: application/json

Then reference it from a page:

---
title: Hello
metadata:
  page-id: hello-world
data:
  comments:
    source: comments
---
This post has {{ len .Data.comments }} comments.

Each entry is available as .Data.<key> in the Markdown file, the page template and the layout. JSON is parsed into structured data, text/html is inserted as HTML and anything else is a plain string. Requests time out after 15 seconds; a failed source logs a warning and leaves its key empty instead of failing the build.

Deploying from CI

Install Gengo in the job, build with --plain and publish the output folder. On GitHub Actions:

- name: Install Gengo
  run: |
    curl -fsSL https://raw.githubusercontent.com/saasuke-labs/gengo/main/install/install.sh | bash
    echo "$HOME/.local/bin" >> "$GITHUB_PATH"

- name: Build
  run: gengo generate --output dist --plain

The source of this website is a complete working example.

Licence

Gengo is free for non-commercial use under the Polyform Noncommercial licence. Using it inside a product or service needs a commercial licence; the details are in the repository.

Using Gengo at work?

Saasuke Labs is independent and maintained in the open. Sponsorship pays for maintenance, documentation and releases.