GoBlog

GoBlog

GoBlog is a blog generation and serving system for creating static blog feeds from Markdown files. It is available as a CLI tool, a Docker image, and an embeddable Go library.

CLI

Install the goblog binary:

go install github.com/harrydayexe/GoBlog/v2/cmd/goblog@latest

# Generate static files
goblog generate posts/ output/

# Serve locally
goblog serve posts/

Global flags

These flags apply to both generate and serve and may be passed before or after the subcommand name.

generate flags

serve flags

When --base-url is set, the server also exposes the generated feeds at {root-path}rss.xml, {root-path}atom.xml, and per-tag feeds at {root-path}tags/{tag}.rss.xml / {root-path}tags/{tag}.atom.xml.

Shell completion

goblog can generate shell completion scripts at runtime. After installing the binary, source the appropriate script to enable tab-completion of subcommands and flags.

Bash — add to ~/.bashrc:

source <(goblog completion bash)

Zsh — add to ~/.zshrc (requires compinit to be loaded):

autoload -Uz compinit && compinit
source <(goblog completion zsh)

Docker

The official image is harrydayexe/goblog. It runs goblog serve --health-checks /posts by default and exposes port 8080. Health-check endpoints are enabled in the Docker image. File watching is off by default; pass --watch to enable it.

Mount your Markdown posts directory to /posts:

docker run -v ./posts:/posts -p 8080:8080 harrydayexe/goblog

The image exposes three health-check endpoints that require no authentication:

To watch for post changes and reload automatically:

docker run -v ./posts:/posts -p 8080:8080 harrydayexe/goblog /posts --watch

Pass any serve flags after the image name — re-supply the posts path as the first argument:

docker run -v ./posts:/posts -p 9000:9000 harrydayexe/goblog /posts --port 9000
docker run -v ./posts:/posts -p 8080:8080 harrydayexe/goblog /posts --root-path /blog/

For custom templates, mount your template directory and use --template-dir:

docker run \
  -v ./posts:/posts \
  -v ./mytheme:/mytheme \
  -p 8080:8080 \
  harrydayexe/goblog /posts --template-dir /mytheme

Library

Add GoBlog as a dependency:

go get github.com/harrydayexe/GoBlog/v2

The main packages are:

A minimal generate-and-write example:

package main

import (
    "context"
    "os"

    "github.com/harrydayexe/GoBlog/v2/pkg/generator"
    "github.com/harrydayexe/GoBlog/v2/pkg/outputter"
    "github.com/harrydayexe/GoBlog/v2/pkg/templates"
)

func main() {
    fsys := os.DirFS("posts/")
    renderer, err := generator.NewTemplateRenderer(templates.Default)
    if err != nil {
        panic(err)
    }

    gen := generator.New(fsys, renderer)
    blog, err := gen.Generate(context.Background())
    if err != nil {
        panic(err)
    }

    writer := outputter.NewDirectoryWriter("output/")
    writer.HandleGeneratedBlog(context.Background(), blog)
}

Logger injection

Every component accepts a structured log/slog logger via config.WithLogger. When not supplied, each component falls back to slog.Default() at construction time.

logger := slog.New(slog.NewTextHandler(os.Stdout, nil))

// Generator and outputter
gen := generator.New(fsys, renderer,
    config.WithLogger(logger).AsGeneratorOption(),
)
writer := outputter.NewDirectoryWriter("output/",
    config.WithLogger(logger).AsGeneratorOption(),
)

// Server
cfg := config.ServerConfig{
    Server: []config.BaseServerOption{
        config.WithPort(8080),
        config.WithLogger(logger).AsServerOption(),
    },
}
srv, err := server.New(nil, postsFS, cfg)

// Watcher
w, err := watcher.New("posts/", config.WithLogger(logger).AsWatcherOption())

// Parser
p := parser.New(parser.WithLogger(logger))

Full API documentation, including all config options and template data types, is at pkg.go.dev/github.com/harrydayexe/GoBlog/v2.

Contributing

Contributions are welcome. See CONTRIBUTING.md for how to set up the project, run tests, and submit pull requests.

License

GNU General Public License v3.0 — see LICENSE for details.