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 | bashTo pin a version:
$ curl -fsSL https://raw.githubusercontent.com/saasuke-labs/gengo/main/install/install.sh | VERSION=0.0.15 bashYou 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.mdThe 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 --watchThe 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.
| Key | What it does |
|---|---|
title | Site title, available to templates. |
default-layout-template | The HTML shell wrapped around every page. |
home-template | Template for the home page, written to index.html. |
default-page-template | Template that wraps the rendered content of a page inside the layout. |
default-section-template | Template for a section's index, which lists its pages. |
static-assets | Folders copied as they are. Each entry has a path and a destination; use destination: . for files that belong at the site root. |
sections | Named groups of pages. The section name becomes the folder in the output. |
sources | HTTP services pages can read at build time. See build-time data. |
Pages
Each entry under a section's pages accepts:
| Key | What it does |
|---|---|
markdown-path | The source file. Markdown is rendered; an .html file is inserted as it is. |
title | Page title. |
description | Short description for listings and meta tags. |
published-at, last-edited-at | Dates you can show or sort by in templates. |
tags | A list of tags. |
metadata | Free-form key/value pairs for your templates. |
data | Which 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:
| Field | Contains |
|---|---|
.Title | The page title. |
.Section | The section name, empty on the home page. |
.Metadata | The page's metadata map. Read a key with {{ index .Metadata "key" }}. |
.HTML | The rendered page content. |
.Data | Build-time data fetched for the page. |
Commands
gengo generate
Builds the site from the manifest.
| Flag | Default | What it does |
|---|---|---|
--manifest | gengo.yaml | Path to the manifest. Can be repeated. |
--output | output | Output directory. |
--plain | off | Plain log output instead of the terminal UI. Use it in CI. |
--watch | off | Rebuild on change, with hot reload. |
gengo serve
Serves a generated site locally.
| Flag | Default | What it does |
|---|---|---|
--site | site | Directory to serve. |
--watch | off | Watch 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/jsonThen 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 --plainThe 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.