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.

--base-url also enables sitemap.xml and robots.txt. With generate, both are written to the top of the output directory; when --root-path is not /, move robots.txt to your domain root on deploy, since crawlers only read /robots.txt.

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. The sitemap is served at {root-path}sitemap.xml, and robots.txt at /robots.txt — the origin root, where crawlers look for it, regardless of --root-path.

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/

Images in ./posts/images are served at /images/ with no extra flags.

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))

SEO metadata

The default templates emit social and search metadata with no template work required:

• Open Graph — og:title, og:description, og:site_name, and og:type (article on posts, website elsewhere). Post pages also emit article:published_time, article:modified_time (from lastEdited), article:author, and one article:tag per tag.
• Schema.org JSON-LD — a BlogPosting object on post pages, carrying the publish and modified dates, author, keywords, reading time, and publisher; a WebSite object elsewhere.
• Canonical URLs — og:url and <link rel="canonical">.
• X/Twitter — twitter:card, which reads its content from the Open Graph tags above.

Canonical URLs need to know the site's domain, so set --base-url (or config.WithBaseURL). Without it, every URL-bearing tag is omitted rather than emitted empty; the rest of the metadata is unaffected.

Setting a base URL also populates GeneratedBlog.Sitemap and GeneratedBlog.RobotsTxt, which pkg/outputter writes as sitemap.xml / robots.txt and pkg/server serves. Opt out with config.WithDisableSitemap() / config.WithDisableRobotsTxt(), or replace the default robots rules with config.WithRobotsTxt(body).

Custom templates can read the same values from the page data: {{.CanonicalURL}}, {{.OGType}}, and {{with .Article}} for the post's publish date, author, and tags. og:image is not emitted — posts have no image field.

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

Front matter

Each post starts with a YAML front matter block:

---
title: "Getting Started"
metaTitle: "Getting Started with GoBlog: A Static Blog Generator in Go"
date: 2026-09-17T10:00:00Z
description: "How to turn a directory of Markdown files into a blog."
tags: [go, tutorial]
author: "Jane Doe"
lastEdited: 2026-09-18T09:00:00Z
---

metaTitle exists because the two jobs title does have different constraints: a heading can be short and rely on page context, while the <title> wants its keyword near the front and has to fit alongside the | {{.SiteTitle}} suffix. Setting it changes the <title>, og:title, and JSON-LD headline only — the heading, post cards, and feed items keep title.

Heading anchor links

Headings get auto-generated ids (## Future Work → id="future-work"). Besides standard [text](#future-work) links, posts can link to a heading in the same post with wikilink syntax:

See [[#Future Work]] or [[#Future Work|what comes next]].

As with standard links, targets are not validated, so a link to a missing heading renders without error. Links to other posts ([[other-post#heading]]) are not supported and render as plain text.

Images

Put images in an images/ directory inside your posts directory and reference them from a post in either form:

![A diagram of the pipeline](images/pipeline.png)
![A diagram of the pipeline](pipeline.png)
![[pipeline.png|A diagram of the pipeline]]

All three render as:

<img src="{root-path}images/pipeline.png" alt="A diagram of the pipeline" width="1200" height="800" loading="lazy" decoding="async" />

The width and height are the image's intrinsic pixel size, read from the asset file while the post is parsed, so the browser can reserve space for the image and the page does not jump as it loads. Files that cannot be measured — missing ones, and formats whose header cannot be decoded such as SVG, AVIF and WebP — simply render without the two attributes. Subdirectories are preserved (images/screenshots/a.png). A bare ![[pipeline.png]] renders with alt="", which tells a screen reader there is nothing to announce; add a |label when the image carries meaning. Absolute URLs and paths starting with / are left as written and get no dimensions, since there is no local file to measure. As with heading links, missing image files are not reported.

Use --assets-dir to keep images elsewhere; if the directory does not exist, image support is simply off. serve reads images straight from disk, so adding or replacing one needs no reload (the directory must exist when the server starts); dimensions are measured at parse time, so swapping in a differently sized image needs a reload for width and height to catch up. generate copies the directory into <output>/images/.

Library users pass the directory with config.WithAssetsDir, ideally via os.Root so symlinks cannot escape it:

root, err := os.OpenRoot("posts/images")
if err != nil {
    panic(err)
}
defer root.Close()

gen := generator.New(postsFS, renderer, config.WithAssetsDir(root.FS()).AsGeneratorOption())
writer := outputter.NewDirectoryWriter("output/", config.WithAssetsDir(root.FS()).AsGeneratorOption())
cfg.Server = append(cfg.Server, config.WithAssetsDir(root.FS()).AsServerOption())

The generator forwards the directory to the parser, which is what measures the images. Using the parser on its own, pass it directly with parser.WithAssetsDir(root.FS()).

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.