Ploggy

A minimalist, fast, and highly-opinionated static site generator for personal websites and blogs. Built with Go, HTML templates, and Tailwind CSS.

Ploggy is designed for developers who appreciate simplicity and want a no-fuss, performant foundation for their personal space on the web. It takes your configuration, Markdown posts, and HTML templates and compiles them into a clean, static website ready for deployment on any modern hosting platform.

Quick Start

Download the latest binary from GitHub Releases and scaffold a new site:

# Download (example for Linux amd64)
curl -L https://github.com/althk/ploggy/releases/latest/download/ploggy_linux_amd64.tar.gz | tar xz

# Scaffold a new site (downloads Tailwind CSS automatically)
./ploggy init my-blog

# Start developing
cd my-blog
ploggy preview

Edit config.toml to personalize your site, then create posts with ploggy new-post "My Post Title".

Features

• Go-Powered: The entire site generation logic is handled by Go, making it fast and dependency-free at runtime.
• Markdown Content: Write your blog posts in standard Markdown with TOML front matter.
• Live Reload Server: A built-in development server watches for changes to your content, templates, and styles, automatically rebuilding the site and reloading your browser.
• Dark Mode: Class-based dark mode with system preference detection and a toggle button. Preference is saved to localStorage.
• RSS Feed: Automatically generates a /feed.xml for readers to subscribe to your blog.
• Sitemap: Generates a /sitemap.xml covering all pages, posts, and tags for SEO.
• Tags: Organize posts with tags. Ploggy generates a /tags/ index and individual /tags/{tag}/ pages.
• Search: Client-side search powered by a build-time JSON index. Searches across titles, descriptions, tags, and content.
• Syntax Highlighting: Code blocks are highlighted with highlight.js using the Atom One Dark theme, with a copy-to-clipboard button on hover.
• Reading Time: Estimated reading time displayed on blog listing and post pages.
• Table of Contents: Auto-generated from h2/h3 headings in post content, displayed as a collapsible section.
• Post Series: Group related posts into a series with ordered navigation between parts.
• Draft Posts: Mark posts as draft = true in front matter to exclude them from the build.
• Open Graph Meta Tags: Per-page title and description for social media sharing.
• Custom 404 Page: A styled 404 page served for missing routes.
• Simple Configuration: Configure your entire site's metadata through a single config.toml file.
• Static Output: A simple build command generates a production-ready, static version of your site in a staging directory.
• Tailwind CSS: Styled with Tailwind CSS for a modern, utility-first approach to design.

Getting Started

The easiest way to start is with the Quick Start above. If you want to build from source or contribute, follow the instructions below.

Prerequisites

• Go (version 1.21 or newer)

Building from Source

1. Clone the repository:

   git clone https://github.com/althk/ploggy.git
   cd ploggy

2. Build the Ploggy Executable:

   go build -o ploggy ./cmd/ploggy

Usage

Initialize a New Site

If you downloaded a pre-built binary or built from source, scaffold a new site:

ploggy init my-blog
cd my-blog

This creates a ready-to-use project with templates, sample config, a starter post, and downloads the Tailwind CSS CLI automatically. You can also use --force to re-scaffold into an existing directory.

Configure Your Site

All personal details and site metadata are controlled by config.toml:

name = "Your Name"
pronouns = "they/them"
nickname = "Your Nickname"
tagline = "Your awesome tagline."
intro = """
A paragraph or two about yourself.
This supports multi-line text.
"""
profile_image = "/images/profile.jpg"
description = "A short site description for RSS and meta tags."

github_url = "https://github.com/your-username"
linkedin_url = "https://www.linkedin.com/in/your-username"
resume_url = "/your-resume.pdf"

Create a New Post

./ploggy new-post "My First Post"

This creates a new Markdown file in posts/ with pre-filled TOML front matter:

+++
title = "My First Post"
description = ""
date = 2026-03-21T10:00:00+05:30
tags = []
draft = false
series = ""
series_order = 0
+++

## My First Post

Start writing...

Front Matter Fields

Field	Type	Description
title	string	Post title
description	string	Short description shown on blog listing and meta tags
date	datetime	Publication date (RFC 3339 format)
tags	array	List of tags, e.g. ["go", "tutorial"]
draft	bool	Set true to exclude from build
series	string	Series name to group related posts
series_order	int	Position within the series (starting from 1)

Run the Development Server

./ploggy preview

This will:

• Build the site into the /staging directory.
• Start a local web server at http://localhost:8080.
• Watch for file changes and automatically reload your browser.

Use -p to specify a different port: ./ploggy preview -p 3000

Build for Production

./ploggy build

This generates a final, optimized version of your site in the /staging directory. You can then upload the contents of this directory to any static hosting service like Vercel, Netlify, or GitHub Pages.

Generated output includes:

• HTML pages for index, blog listing, individual posts, tags, search, and 404
• /feed.xml — RSS feed
• /sitemap.xml — Sitemap for search engines
• /search-index.json — Search index for client-side search
• /css/styles.css — Compiled and minified Tailwind CSS

Customization

• HTML Structure: Layouts are in /templates. Edit base.html (main layout) and page templates (index.html, blog.html, post.html, tags.html, 404.html, search.html).
• Styling: Handled by Tailwind CSS. Modify the design system in tailwind.config.js and add custom CSS to static/css/input.css.
• Dark Mode: Uses class-based Tailwind dark mode. The toggle is in the header. Add dark: variants to any Tailwind class in templates.

Directory Structure

├── cmd/ploggy/      # CLI entrypoint (Cobra commands)
├── internal/core/   # Core logic (builder, server, types)
├── posts/           # Markdown blog posts
├── static/          # Static assets (images, CSS input)
├── staging/         # Generated static site (output)
├── templates/       # HTML templates
├── config.toml      # Site configuration
└── tailwind.config.js