HTTP/Minimal Reference Server#

A reference implementation of an HTTP/Minimal compliant server in Go.

Features#

• Serves Markdown files with proper text/markdown Content-Type
• Content negotiation: serves HTML to browsers, Markdown to clients that request it
• Strips raw HTML from Markdown sources (compliance enforcement)
• YAML front matter support for metadata
• /.well-known/http-minimal endpoint
• Method restrictions (GET/HEAD only)
• Forbidden header removal
• Designed to run behind nginx/Caddy reverse proxy

Quick Start#

# Install dependencies
go mod download

# Run the server
go run main.go -dir ./content -port 8080

Usage#

Usage of http-minimal-server:
 -port string
        Listen port (default "8080")
 -base-url string
        Base URL for the site (default "http://localhost:8080")
 -contact string
        Contact email for /.well-known/http-minimal
 -dir string
        Content directory (default "./content")
 -template string
        HTML template file (default: built-in template)

Content Directory Structure#

content/
├── index.md          # Served at /
├── about.md          # Served at /about
├── posts/
│   ├── index.md      # Served at /posts
│   └── first.md      # Served at /posts/first
└── images/
    └── logo.png      # Served at /images/logo.png

Front Matter#

Documents can include YAML front matter:

---
title: My Page Title
author: Jane Doe
date: 2025-12-27
lang: en
license: CC0-1.0
---

# Content starts here

Content Negotiation#

The server respects the Accept header:

# Get HTML (default for browsers)
curl http://localhost:8080/

# Get raw Markdown
curl -H "Accept: text/markdown" http://localhost:8080/

# Check compliance policy
curl http://localhost:8080/.well-known/http-minimal

Compliance#

The server enforces HTTP/Minimal compliance:

• Methods: Only GET and HEAD are allowed
• Response Headers: Forbidden headers (Set-Cookie, WWW-Authenticate, etc.) are removed
• Content: Raw HTML is stripped from Markdown before serving
• Validation: Images without alt text are logged as warnings

Extending#

Custom HTML Template#

Modify the htmlTemplate constant in main.go to customize the HTML rendering. Keep it minimal - no JavaScript, no external resources except same-origin images.

Adding Middleware#

The server implements http.Handler, so you can wrap it with standard Go middleware:

server, _ := NewServer(config)
handler := loggingMiddleware(server)
http.ListenAndServe(":8080", handler)

Integration with AT Protocol#

The /.well-known/http-minimal endpoint could be extended to include:

{
  "http_minimal": "0.1",
  "compliant": true,
  "did": "did:plc:example",
  "atproto_pds": "https://bsky.social"
}

Dependencies#

• goldmark - Markdown parser (CommonMark + GFM)
• yaml.v3 - YAML front matter parsing

License#

This reference implementation is released under CC0 1.0 Universal - no rights reserved.