markata-go

markata-go

A fast, plugin-driven static site generator with a powerful feed system.

Overview

markata-go is a static site generator written in Go that processes Markdown files with YAML frontmatter and generates a complete static website. It features a flexible plugin architecture, a powerful feed system for creating archives and syndication feeds, and Jinja2-like templating.

Status: Beta (0.x) - API may change between minor versions

Key Features

• Plugin-driven architecture - Extensible system with 30+ built-in plugins
• Powerful feed system - Define feeds with filtering, sorting, and pagination; generate multiple output formats (HTML, RSS, Atom, JSON) from a single definition
• Jinja2-like templates - Familiar template syntax via pongo2 with custom filters
• 9-stage lifecycle - Configure, Validate, Glob, Load, Transform, Render, Collect, Write, Cleanup
• Concurrent processing - Parallel processing with configurable worker count
• Markdown with extensions - GFM tables, strikethrough, task lists, admonitions, syntax highlighting, wikilinks, and table of contents generation
• Live reload development server - Built-in server with file watching and automatic rebuilds

Installation

Quick Install (Recommended)

# One-liner install script (Linux/macOS)
curl -sSL https://raw.githubusercontent.com/WaylonWalker/markata-go/main/install.sh | bash

# Using jpillora/installer (Linux/macOS)
curl -sL https://i.jpillora.com/WaylonWalker/markata-go | bash

# Using eget
eget WaylonWalker/markata-go

# Using mise (installs from GitHub releases)
mise use -g github:WaylonWalker/markata-go

Go Install

go install github.com/WaylonWalker/markata-go/cmd/markata-go@latest

Manual Download

Download pre-built binaries from GitHub Releases.

Available platforms: Linux (amd64, arm64, armv7), macOS (Intel, Apple Silicon), Windows (amd64), FreeBSD (amd64), Android (arm64/Termux).

See docs/installation.md for detailed installation instructions.

Quick Start

# Create a new post
markata-go new "Hello World"

# Build the site
markata-go build

# Serve with live reload
markata-go serve

Configuration

markata-go uses TOML configuration (also supports YAML and JSON). Create a markata-go.toml in your project root:

[markata-go]
# Site metadata
title = "My Site"
description = "A site built with markata-go"
url = "https://example.com"
author = "Your Name"

# Build settings
output_dir = "public"
templates_dir = "templates"
assets_dir = "static"

# Concurrency (0 = auto based on CPU cores)
concurrency = 0

# Plugin configuration
hooks = ["default"]
disabled_hooks = []

# Content discovery
[markata-go.glob]
patterns = ["posts/**/*.md", "pages/*.md"]
use_gitignore = true

# Markdown extensions
[markata-go.markdown]
extensions = ["tables", "strikethrough", "autolinks", "tasklist"]

# Reading time calculation
[markata-go.reading_time]
words_per_minute = 200

# Auto-generated descriptions
[markata-go.description]
max_length = 160

# Table of contents
[markata-go.toc]
min_level = 2
max_level = 4

# Wikilinks
[markata-go.wikilinks]
warn_broken = true

Environment Variable Overrides

All configuration options can be overridden via environment variables using the MARKATA_GO_ prefix:

MARKATA_GO_OUTPUT_DIR=dist markata-go build
MARKATA_GO_URL=https://staging.example.com markata-go build
MARKATA_GO_CONCURRENCY=4 markata-go build

Content

Frontmatter Format

Posts use YAML frontmatter to define metadata:

---
title: "My First Post"
slug: "my-first-post"
date: 2024-01-15
published: true
draft: false
tags: ["go", "static-site"]
description: "An introduction to markata-go"
template: "post.html"
---

Supported Fields

Any additional fields in frontmatter are stored in Extra and accessible in templates.

Feed System

The feed system is markata-go's most powerful feature. Define feeds to create filtered, sorted, paginated collections of posts with multiple output formats.

Feed Configuration

# Feed defaults - inherited by all feeds
[markata-go.feed_defaults]
items_per_page = 10
orphan_threshold = 3

[markata-go.feed_defaults.formats]
html = true
rss = true
atom = false
json = false

[markata-go.feed_defaults.templates]
html = "feed.html"
card = "card.html"

[markata-go.feed_defaults.syndication]
max_items = 20
include_content = true

Defining Feeds

# Main blog feed
[[markata-go.feeds]]
slug = "blog"
title = "Blog"
description = "All blog posts"
filter = "published == True"
sort = "date"
reverse = true
items_per_page = 10

[markata-go.feeds.formats]
html = true
rss = true
atom = true
json = true

# Home page (empty slug = root index.html)
[[markata-go.feeds]]
slug = ""
title = "Latest Posts"
filter = "published == True"
sort = "date"
reverse = true
items_per_page = 5

[markata-go.feeds.formats]
html = true

# Featured posts
[[markata-go.feeds]]
slug = "featured"
title = "Featured"
description = "Featured posts"
filter = "published == True and featured == True"
sort = "date"
reverse = true

Multiple Output Formats

Each feed can generate multiple formats from a single definition:

CLI Commands

markata-go build

Build the static site.

markata-go build              # Standard build
markata-go build --clean      # Clean output directory first
markata-go build --dry-run    # Show what would be built
markata-go build -v           # Verbose output
markata-go build -o dist      # Custom output directory

markata-go serve

Development server with live reload.

markata-go serve              # Serve on localhost:8000
markata-go serve -p 3000      # Custom port
markata-go serve --host 0.0.0.0  # Bind to all interfaces
markata-go serve --no-watch   # Disable file watching
markata-go serve -v           # Verbose logging

markata-go new <title>

Create a new post.

markata-go new "My First Post"         # Creates posts/my-first-post.md
markata-go new "Hello World" --dir blog  # Creates blog/hello-world.md
markata-go new "Draft" --draft          # Create as draft (default)
markata-go new "Published" --draft=false # Create as published

markata-go config

Configuration management commands.

markata-go config show           # Show resolved config (YAML)
markata-go config show --json    # Show as JSON
markata-go config show --toml    # Show as TOML

markata-go config get output_dir          # Get specific value
markata-go config get glob.patterns       # Nested values with dot notation

markata-go config validate       # Validate configuration

markata-go config init           # Create markata-go.toml
markata-go config init site.yaml # Create YAML config
markata-go config init --force   # Overwrite existing

markata-go version

Show version information.

markata-go version           # Full version info
markata-go version --short   # Just the version number
markata-go --version         # Short version flag

Global Flags

-c, --config string   Config file path (default: auto-discover)
-o, --output string   Output directory (overrides config)
-v, --verbose         Verbose output

Documentation

• Installation Guide - Detailed installation instructions
• Configuration Guide - Full configuration reference
• CLI Reference - All CLI commands and options
• Plugin Reference - Built-in plugins documentation

Development

Building from Source

# Clone the repository
git clone https://github.com/WaylonWalker/markata-go.git
cd markata-go

# Build
just build

# Run tests
just test

# Run all quality checks
just check

Using just

The project uses just for development commands:

just build          # Build with version info
just test           # Run tests
just test-race      # Run tests with race detector
just lint           # Run linters
just check          # Run all quality checks (fmt, vet, lint, test)
just snapshot       # Test goreleaser locally
just ci             # Run what CI runs

See the justfile for all available commands.

Contributing

This project is open source but not open contribution. See CONTRIBUTING.md for details.

If you want to build your own static site generator, feel free to fork this project or use the spec as a starting point for your own implementation.

Inspiration

• markata - The Python SSG this project is based on
• Hugo - Fast builds, good CLI
• Eleventy - Plugin flexibility
• Zola - Single binary simplicity

License

MIT License - see LICENSE for details.

Copyright (c) 2024 Waylon Walker