Technical Implementation: Building a Modern Static Blog with Go and Retro Terminal Aesthetics

This blog represents a complete technical implementation of a modern static site generator built from scratch using Go, featuring a distinctive retro terminal aesthetic and comprehensive tooling for content management and deployment.

Architecture Overview

Core Technology Stack

Backend Framework: - Go 1.21+ - Primary backend language - Gin Web Framework - HTTP server and routing - YAML v3 - Configuration and frontmatter parsing - Gomarkdown - Markdown to HTML conversion with extensions - Bluemonday - HTML sanitization for security

Frontend Technologies: - Vanilla JavaScript - Client-side functionality without framework dependencies - CSS3 with Custom Properties - Advanced styling with CSS variables - HTML5 Semantic Elements - Proper document structure

Development & Deployment: - GitHub Actions - Automated CI/CD pipeline - GitHub Pages - Static site hosting - Make - Build automation and task management

System Architecture

Static Site Generation Pipeline

The system implements a dual-mode architecture:

  1. Development Mode: Live admin interface for content creation and editing
  2. Production Mode: Static HTML generation for deployment
func main() {
    if len(os.Args) > 1 && os.Args[1] == "build" {
        buildSite()
        return
    }
    // Admin server mode
    r := gin.Default()
    // ... server configuration
}

Content Management System

Post Structure:

type Post struct {
    Title       string        `yaml:"title" json:"title"`
    Date        time.Time     `yaml:"date" json:"date"`
    Description string        `yaml:"description" json:"description"`
    Tags        []string      `yaml:"tags" json:"tags"`
    Draft       bool          `yaml:"draft" json:"draft"`
    Slug        string        `yaml:"slug" json:"slug"`
    Content     string        `json:"content"`
    HTMLContent template.HTML `json:"-"`
}

Configuration Management:

type Config struct {
    SiteTitle       string `yaml:"site_title"`
    SiteDescription string `yaml:"site_description"`
    BaseURL         string `yaml:"base_url"`
    Author          string `yaml:"author"`
}

Technical Features Implementation

Markdown Processing Pipeline

The system implements a sophisticated markdown processing pipeline with security considerations:

func markdownToHTML(md string) template.HTML {
    extensions := parser.CommonExtensions | parser.AutoHeadingIDs
    p := parser.NewWithExtensions(extensions)
    doc := p.Parse([]byte(md))

    htmlFlags := html.CommonFlags | html.HrefTargetBlank
    opts := html.RendererOptions{Flags: htmlFlags}
    renderer := html.NewRenderer(opts)

    htmlBytes := markdown.Render(doc, renderer)

    p2 := bluemonday.UGCPolicy()
    p2.AllowElements("h1", "h2", "h3", "h4", "h5", "h6")
    p2.AllowAttrs("id").OnElements("h1", "h2", "h3", "h4", "h5", "h6")

    return template.HTML(p2.SanitizeBytes(htmlBytes))
}

Key Features: - Automatic heading ID generation for deep linking - External link security (target="_blank") - HTML sanitization preventing XSS attacks - Support for code blocks, tables, and advanced markdown features

Retro Terminal UI Implementation

The distinctive terminal aesthetic is achieved through advanced CSS techniques:

Core Visual Elements:

:root {
    --bg-primary: #0a0a0a;
    --bg-secondary: #111111;
    --text-primary: #ffaa00;
    --accent: #ffaa00;
    --glow: rgba(255, 170, 0, 0.5);
}

CRT Screen Effects: - Scanline animation with CSS keyframes - RGB phosphor simulation - Screen flicker effect - Text glow and shadow effects - Terminal cursor blinking animation

Advanced CSS Features:

/* Scan line effect */
body::after {
    content: '';
    position: fixed;
    background: linear-gradient(90deg, transparent, var(--glow), transparent);
    animation: scanline 8s linear infinite;
}

@keyframes scanline {
    0% { top: -2px; opacity: 1; }
    100% { top: 100vh; opacity: 0; }
}

Admin Panel Architecture

The admin interface provides comprehensive content management capabilities:

RESTful API Endpoints: - GET /posts - Retrieve all posts - POST /posts - Create new post - GET /posts/:slug - Retrieve specific post - PUT /posts/:slug - Update existing post - DELETE /posts/:slug - Delete post - POST /build - Trigger site build

Frontend Features: - Real-time post preview - Draft/published status management - Tag management system - Markdown editor with syntax highlighting - Build status monitoring

File System Organization

project/
├── content/posts/          # Markdown content files
├── static/css/            # Stylesheets
│   ├── retro-terminal.css # Public site styles
│   └── admin.css         # Admin panel styles
├── templates/             # HTML templates
├── docs/                 # Generated static site
├── .github/workflows/    # CI/CD configuration
└── main.go              # Core application

Build System & Automation

Makefile Implementation

Comprehensive build automation with help system:

.PHONY: help build start check clean
.DEFAULT_GOAL := help

help: ## Show this help message
	@echo "Available commands:"
	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | \
		awk 'BEGIN {FS = ":.*?## "}; {printf "  %-12s %s\n", $$1, $$2}'

build: ## Build static site
	@echo "🔨 Building static site..."
	@go run main.go build
	@echo "✅ Site built in docs/"

GitHub Actions Workflow

Automated deployment pipeline with security considerations:

name: Deploy to GitHub Pages
on:
  push:
    branches: [ main ]
  workflow_dispatch:

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pages: write
      id-token: write
    
    steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-go@v4
      with:
        go-version: '1.21'
    
    - name: Build site
      run: make build
    
    - name: Deploy to GitHub Pages
      uses: actions/deploy-pages@v3

Security Implementation

Content Sanitization

Multiple layers of security for user-generated content:

  1. HTML Sanitization: Bluemonday policy preventing script injection
  2. Input Validation: Server-side validation of all form inputs
  3. YAML Parsing: Safe parsing with bounds checking
  4. File System Access: Restricted to designated content directories

Development Security

  • No sensitive data in version control
  • Environment-specific configuration
  • HTTPS enforcement in production
  • CSP headers for additional protection

Performance Optimizations

Static Asset Management

  • CSS minification and optimization
  • Font loading optimization with font-display: swap
  • Efficient CSS custom properties usage
  • Minimal JavaScript footprint

Build Performance

  • Efficient Go routines for concurrent operations
  • Optimized file I/O operations
  • Smart caching strategies
  • Incremental build support

Deployment Strategy

Production Build Process

  1. Content Compilation: Markdown to HTML conversion
  2. Asset Optimization: CSS and static file processing
  3. Template Rendering: Dynamic content generation
  4. Static File Generation: Complete site export to docs/

GitHub Pages Integration

  • Automatic deployment on main branch push
  • Custom domain support with SSL
  • CDN integration for global distribution
  • Automated dependency updates

Code Quality & Maintenance

Development Standards

  • Go Best Practices: Idiomatic Go code with proper error handling
  • Documentation: Comprehensive inline documentation
  • Testing Strategy: Unit tests for core functionality
  • Code Organization: Clear separation of concerns

Internationalization

Complete English implementation for global accessibility: - UI text translation - Date/time formatting - Error messages - Documentation

Future Enhancements

Planned Features

  • Search Functionality: Full-text search implementation
  • RSS Feed Generation: Automated feed creation
  • Comment System: Integration with external comment services
  • Analytics Integration: Privacy-focused analytics
  • Progressive Web App: Offline functionality

Scalability Considerations

  • Content Management: Database integration for larger content volumes
  • Performance: CDN integration and advanced caching
  • Multi-language Support: i18n framework implementation

Conclusion

This implementation represents a modern approach to static site generation, combining the performance benefits of static sites with the convenience of dynamic content management. The retro terminal aesthetic provides a unique visual identity while maintaining excellent usability and accessibility standards.

The system demonstrates advanced Go programming techniques, modern web development practices, and comprehensive DevOps automation, creating a robust foundation for technical content publication and management.

Key Technical Achievements: - Zero-dependency frontend with advanced CSS effects - Secure content processing pipeline - Comprehensive automation and deployment - Modern Go application architecture - Professional development workflow

The complete source code and documentation are available for review and contribution, representing a practical example of modern web development best practices in the Go ecosystem.