gozer

README

Gozer!

Gozer is a fast & simple static site generator written in Golang.

• Converts Markdown and djot to HTML.
• Allows you to use page-specific templates.
• Creates an XML sitemap for search engines.
• Creates an RSS feed for feed readers.

Sample websites using Gozer:

• Simplest possible example
• dvko's personal website: site - source
• My personal website, using the Gozer Tufte theme.

Soft Fork

This is my (SER) development fork of Gozer, with the pending patches which have not yet been accepted upstream. These are:

• watch function, which puts Gozer into the same "watch and rebuild" state as serve, but without starting an HTTP listener.
• -listen flag, for specifying which interface:port to listen on. This is used with the existing serve function, which is currently hard-coded to localhost:8080 in upstream.
• Attributes in config.toml and in page front-matter are now accessible by template through .Site.Attrs and .Page.Attrs. These are Go maps, so the usual .Site.Attrs.author accessors work.
• Adds support for organizing posts by path, rather than by magic patterns in in file names. This means blog entries can be added to e.g. a posts/ directory without requiring putting the publication date in the file name.

The main branch of this is go install-able:

$ go install git.sr.ht/~ser/gozer

or clone and build:

$ git clone --depth 1 https://git.sr.ht/~ser/gozer
$ cd gozer
$ go build .

and then copy the resulting gozer binary into your path.

You are free to use this fork, but it's a soft fork with patches sent upstream.

Installation

You can install Gozer by first installing a Go compiler and then running:

go install git.sr.ht/~ser/gozer@latest

Usage

Run gozer new to quickly generate an empty directory structure.

├── config.toml                # Configuration file
├── content                    # Posts and pages
│   └── index.md
├── public                     # Static files
└── templates                  # Template files
    └── default.html

Then, run gozer build to generate your site.

Any Markdown files placed in your content/ directory will result in an HTML page in your build directory after running gozer build.

For example:

• content/index.md creates a file build/index.html so it is accessible over HTTP at /
• content/about.md creates a file build/about/index.html so it is accessible over HTTP at /about/.

Configuration

The configuration file, config.toml, is either in the top-level site directory or is specified in gozer command-line arguments. All tags in this file are available to templates through the .Site.Attrs field, and some are used by gozer directly for configuring the site. All attributes are optional, although some templates may expect some attributes to exist and may produce errors if they're missing. Each template should declare which fields are mandatory.

• title: Required Contains the title of the site, mainly used in templates
• baseurl: Required Contains the live URL
• posts: Optional A directory containing posts. Defaults to taking dates from post filenames.

The last two option applies only to posts. If posts is not provided, posts are identified by a filename starting with an ISO8601 date (without time), such as 2006-01-02-my-blog-post.md. In this case, every file starting with a date like this is identified as a post, and the DatePublished is set to the date in the file name. This is backwards-compatible with prior versions of Gozer, so to continue using dates in filenames, do not set this option.

If posts is set, dates in filenames are ignored, and the publication date is taken from a date = <ISO8601> front matter attribute. If this attribute is missing, Gozer will use the filesystem-reported file birth date.

e.g.

url = http://localhost:8080
title = "My website"
posts = "posts"

Commands

Run gozer without any arguments to view the help text.

Gozer - a fast & simple static site generator

Usage: gozer [OPTIONS] <COMMAND>

Commands:
    build   Deletes the output directory if there is one and builds the site
    serve   Builds the site and starts an HTTP server on http://localhost:8080
    watch   Builds the site and watches for file changes
    new     Creates a new site structure in the given directory

Options:
    -r, --root <ROOT> Directory to use as root of project (default: .)
    -c, --config <CONFIG> Path to configuration file (default: config.toml)
        --listen <INTERFACE:PORT> Interface to liston on; only used with 'serve',
                 'INTERFACE' is optional. e.g. '--listen :9000'

Content files

Each file in your content/ directory should end in .md or .dj and have TOML front matter specifying the page title:

+++
title = "My page title"
+++

Page content here.

djot note djot has not settled on a syntax for front matter. Until issue #35 is resolved, TOML front matter in djot documents are used.

Templates

The default template for every page is default.html. You can override it by setting the template variable in your front matter.

+++
title = "My page title"
template = "special-page.html"
+++

Page content here.

Templates are powered by Go's standard html/template package, so you can use all the actions described here.

Every template receives the following set of variables:

Pages       # Slice of all pages in the site
Posts       # Slice of all posts in the site (any page identified as a post, see the config)
Site        # Global site properties: Url, Title
Page        # The current page: Title, Permalink, UrlPath, DatePublished, DateModified
Title       # The current page title, shorthand for Page.Title
Content     # The current page's HTML content.
Now         # Timestamp of build, instance of time.Time

The Page variable is an instance of the object below:

type Page struct {
    // Title of this page
    Title         string

    // Template this page uses for rendering. Defaults to "default.html".
    Template      string

    // Time this page was published (parsed from file name).
    DatePublished time.Time

    // Time this page was last modified on the filesystem.
    DateModified  time.Time

    // The full URL to this page, including the site URL.
    Permalink     string

    // URL path for this page, relative to site URL
    UrlPath       string

    // Path to source file for this page, relative to content root
    Filepath      string
}

To show a list of the 5 most recent posts:

{{ range (slice .Posts 0 5) }}
    <a href="{{ .Permalink }}">{{ .Title }}</a> <small>{{ .DatePublished.Format "Jan 02, 2006" }}</small><br />
{{ end }}

New Templates

Templates are free to use whichever front-matter or config metadata they choose; however, it is preferrable to follow conventions to make changing templates easier for users. Experience with Hugo template has shown that without conventions, switching templates becomes a chore. Therefore, template builders are advised to use the attributes in conventions.toml where possible; and if new attributes are needed, it would benefit the ecosystem if patches to add attributes to the conventions.toml file. In these cases, please include a description for each attribute.

Contributing

Gozer development happens on Sourcehut. Patches are accepted over email.

• Code repository

License

Gozer is open-sourced under the MIT license.