GoBlog

---

Code Quality & Testing

Test Coverage (main branch): 88.6%

Note: The coverage percentage above reflects the main branch. For branch-specific coverage, see the automated comment on any pull request or check the workflow artifacts.

• 📊 Coverage reports generated using Go's built-in go tool cover
• 🎯 80% minimum coverage enforced via CI
• 📝 Detailed testing guide: TESTING.md
• 💬 PR comments show branch-specific coverage with package breakdown

---

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • GoBlogGen Usage
3. Contributing
4. License
5. Contact

About The Project

GoBlog is a two-part system for creating and serving markdown-based blogs. Write your posts in markdown and let GoBlog handle the rest.

GoBlogGen

Unopinionated static site generator for markdown blogs.

GoBlogGen converts your markdown posts into static HTML pages. You control the templates, styling, and structure. The generated output is pure HTML/CSS that can be deployed anywhere.

Features:

• YAML frontmatter for post metadata
• Customizable HTML templates
• Syntax highlighting for code blocks
• Tag-based organization
• Pagination support

Perfect for: Developers who want full control over their blog's appearance and hosting.

GoBlogServ

Opinionated web server with HTMX-powered interactivity.

GoBlogServ provides two ways to add dynamic features to your blog:

1. Go Library: Import into your Go application for custom integration
2. Standalone Server: Run as a binary or Docker container for turnkey deployment

Features:

• Real-time search (powered by Bleve)
• Tag filtering and pagination
• HTMX for dynamic updates without page reloads
• In-memory caching (Ristretto)
• Single binary deployment
• Docker support for sidecar pattern

Perfect for: Developers who want interactive features without complex JavaScript frameworks.

(back to top)

Built With

• 

(back to top)

Getting Started

Installation

Option 1: Homebrew (macOS/Linux)

brew install harrydayexe/goblog/gobloggen

Option 2: Direct Download

Download the latest release for your platform from the releases page.

Linux/macOS:

# Download and extract
tar -xzf gobloggen_*_<your-platform>.tar.gz

# Move to PATH
sudo mv gobloggen /usr/local/bin/

# Verify installation
gobloggen -help

Windows:

# Extract the .zip file
# Add the directory to your PATH or move gobloggen.exe to a directory in PATH

# Verify installation
gobloggen.exe -help

Option 3: Go Install (For Go Developers)

go install github.com/harrydayexe/GoBlog/cmd/GoBlogGen@latest

Quick Start

1. Create a directory for your blog posts:

   mkdir posts
   

2. Create a sample post with YAML frontmatter:

   cat > posts/hello-world.md << 'EOF'
   ---
   title: "Hello World"
   date: 2025-01-15
   description: "My first blog post"
   tags: ["intro", "blogging"]
   draft: false
   ---
   
   # Hello World
   
   This is my first blog post using GoBlog!
   
   ```go
   package main
   
   func main() {
       println("Hello, Blog!")
   }
   

   EOF

3. Create a configuration file:

   cat > config.yaml << 'EOF'
   input_folder: "./posts"
   output_folder: "./site"
   site:
     title: "My Blog"
     description: "A blog about development"
     author: "Your Name"
   EOF
   

4. Generate your site:

   gobloggen -config config.yaml
   

5. Your static site is now in ./site/ and ready to deploy!

Customizing Templates

GoBlog uses HTML templates for rendering your blog. You can customize the look and feel by creating your own templates.

Using Default Templates

By default, GoBlog uses templates from ./templates/defaults/. These include:

• post.html - Individual blog post page
• index.html - Blog index/list page
• tag.html - Tag filter page

Creating Custom Templates

1. Create a new directory for your templates:

   mkdir ./my-templates
   

2. Copy the default templates as a starting point:

   cp templates/defaults/* ./my-templates/
   

3. Edit the templates to match your design. Each template must exist:

   • post.html
   • index.html
   • tag.html

4. Update your config.yaml:

   template_dir: "./my-templates"
   

Template Data

Templates have access to the following data:

post.html:

• .Post.Title - Post title
• .Post.Description - Post description
• .Post.FormattedDate - Human-readable date
• .Post.ShortDate - ISO date (YYYY-MM-DD)
• .Post.Tags - Array of tags
• .Post.HTMLContent - Rendered HTML content
• .Site.Title - Site title
• .Site.Description - Site description
• .Site.Author - Site author
• .BlogPath - Blog URL path

index.html:

• .Posts - Array of posts for this page
• .AllTags - Array of all tags across all posts
• .Page - Current page number
• .TotalPages - Total number of pages
• .HasNext - Boolean, true if there's a next page
• .HasPrev - Boolean, true if there's a previous page
• .Site.* - Site metadata (same as post.html)
• .BlogPath - Blog URL path

tag.html:

• .Tag - Current tag being filtered
• .Posts - Array of posts with this tag
• .AllTags - Array of all tags across all posts
• .Site.* - Site metadata
• .BlogPath - Blog URL path

Template Functions

The following functions are available in templates:

• {{add .Page 1}} - Add two numbers
• {{sub .Page 1}} - Subtract two numbers

See templates/defaults/ for complete examples.

(back to top)

GoBlogServ Usage

GoBlogServ adds dynamic features to your blog through two distribution models.

Option 1: Go Library (For Developers)

Import GoBlogServ into your existing Go application:

package main

import (
    "net/http"
    "github.com/harrydayexe/GoBlog/pkg/server"
)

func main() {
    // Create blog server instance
    blog := server.New(server.Config{
        ContentFolder: "./posts",
        CacheSize: 100,
    })

    // Mount to your existing router
    mux := http.NewServeMux()
    mux.Handle("/blog/", blog.Routes())

    // Or use individual handlers for custom routing
    mux.HandleFunc("GET /blog/{slug}", blog.PostHandler)
    mux.HandleFunc("GET /api/search", blog.SearchHandler)

    http.ListenAndServe(":8080", mux)
}

Install the library:

go get github.com/harrydayexe/GoBlog/pkg/server

Option 2: Standalone Binary

Run GoBlogServ as a standalone server:

# Install via Homebrew
brew install harrydayexe/goblog/goblogserv

# Or via Go install
go install github.com/harrydayexe/GoBlog/cmd/GoBlogServ@latest

# Run with configuration file
goblogserv -config server.yaml

# Or with command-line flags
goblogserv -content ./posts -port 8080

Option 3: Docker Container

Run GoBlogServ in a container:

# Pull and run
docker run -v ./posts:/posts -p 8080:8080 harrydayexe/goblogserv:latest

# With custom configuration
docker run -v ./config.yaml:/config.yaml \
           -v ./posts:/posts \
           -p 8080:8080 \
           harrydayexe/goblogserv:latest -config /config.yaml

Docker Compose (Sidecar Pattern)

version: '3.8'
services:
  app:
    build: .
    ports:
      - "3000:3000"

  blog:
    image: harrydayexe/goblogserv:latest
    volumes:
      - ./posts:/posts
    environment:
      - GOBLOG_CONTENT_FOLDER=/posts
      - GOBLOG_PORT=8080
    ports:
      - "8080:8080"

Configuration

Create a server.yaml configuration file:

server:
  host: "localhost"
  port: 8080

content_folder: "./posts"

cache:
  max_size_mb: 100
  ttl_minutes: 60

search:
  index_path: "./blog.bleve"
  rebuild_on_start: false

blog:
  path: "/blog"
  posts_per_page: 10

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

For Maintainers

If you're setting up the repository for the first time or managing GitHub Actions workflows, see .github/SETUP.md for information on required secrets and workflow configuration.

(back to top)

Top contributors:

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Harry Day - @harrydayexe - contact@harryday.xyz

Project Link: https://github.com/harrydayexe/GoBlog

(back to top)