Docs · inkssg

Install

go install github.com/snowztech/inkssg/cmd/inkssg@latest

Or download a binary from Releases. Check it with inkssg version.

Quick start

inkssg new my-site
inkssg build my-site

new creates ink.yaml and pages/index/content.md. build writes the site to my-site/public/. Edit content.md and build again. The public/ folder is what you deploy.

Dev server

inkssg serve my-site

Builds the site, serves it at http://localhost:3000, watches your files, and reloads the browser on every change. Pass --addr :4000 for another port.

Site layout

Everything is optional except pages/.

my-site/
├── ink.yaml       site-wide data
├── pages/         one folder per page     → /<name>.html
├── themes/        your own themes
├── assets/        images, fonts, icons    → /assets/...
└── static/        files that need a root URL → /...

Pages

Each page is a folder in pages/. The folder name becomes the file name.

pages/
├── index/content.md     → index.html
├── about/content.md     → about.html
└── contact/content.html → contact.html

Write content.md for prose. Write content.html when you want full control: it goes into the layout unchanged.

Frontmatter

Optional metadata at the top of content.md or content.html:

---
title: About
description: A short blurb
theme: devtool
---

Field	What it does
`title`	The page title, as `.Page.Title`
`description`	The meta description, as `.Page.Description`
`theme`	A theme for this page only

ink.yaml

Optional. Data shared by every page, available in templates as .Site. Use frontmatter for one page, ink.yaml for the whole site.

name: My Site
default_theme: devtool
output_dir: public
meta:
  lang: en
  title: My Site
  description: Site description
links:
  - name: GitHub
    url: https://github.com/user

Field	What it does
`name`	Site name, as `.Site.Name`
`default_theme`	Theme for pages that don't set one. Defaults to `minimal`
`output_dir`	Where the site is written. Defaults to `public`, must be inside the project
`pages_dir`	Where pages live. Defaults to `pages`
`meta`	`lang`, `title`, `description`, `author`, `siteUrl`
`links`	A list of `name` and `url`

The built-in themes also read avatar, bio, status, install, projects and contact.socials. Your own theme can use any of them.

Themes

Three themes are built into the binary: minimal (the default), devtool and bio. Pick one with default_theme in ink.yaml, or theme in a page's frontmatter.

To make your own, add a folder to themes/. Only layout.html is required. A local theme with the same name as a built-in one replaces it.

themes/
└── landing/
    ├── layout.html   required
    ├── styles.css    optional
    └── script.js     optional

Theme files are published at /themes/<name>/, so link them as /themes/landing/styles.css. The layout is a Go template:

<!doctype html>
<html lang="{{.Site.Meta.Lang}}">
  <head>
    <title>{{.Page.Title}}</title>
    <link rel="stylesheet" href="/themes/landing/styles.css">
  </head>
  <body>{{.Content}}</body>
</html>

Value	What it holds
`.Content`	The rendered page
`.Page`	`Name`, `Title`, `Description`
`.Site`	The fields from `ink.yaml`, only when it exists
`.Theme`	Theme data

Assets and static files

Folder	Served at	Use for
`assets/`	`/assets/<path>`	Images, fonts and icons your pages use
`static/`	`/<path>`	Files that need an exact root URL: `robots.txt`, `CNAME`, a hand-written HTML page

Both are copied as they are, dotfiles included. Nothing in static/ is rendered or wrapped in a theme. If you're not sure, use assets/.

The build copies in this order, and later steps win:

theme files → public/themes/<name>/
assets/ → public/assets/
static/ → public/
pages → public/<name>.html

So a page always wins: static/index.html does not replace the page from pages/index/.

Use it from Go

go get github.com/snowztech/inkssg

import "github.com/snowztech/inkssg"

if err := inkssg.Build("./my-site"); err != nil {
    log.Fatal(err)
}

With no argument, inkssg.Build() builds the current directory. The CLI calls the same function.

Build output

✓ index → index.html
✓ about → about.html
built 2 pages in 3ms

Every page is built, every error is reported, and the command exits non-zero if any page fails.

Complete sites live in examples/, including one that uses the Go library.

Edit this page on GitHub