Static Repo Generator

A modern, fast static site generator written in Go. It transforms a directory of files (Markdown, code, media, PDFs) into a navigable project documentation site with an overview page and per-project navigation.

Features

  • Project Overview Page: Generates a top-level index page listing all projects.
  • Root README Support: Uses content/README.md as overview content on the top-level page.
  • Frontmatter Metadata: Reads title, description, and date from each project's README.md.
  • External Project Imports: Optionally downloads project ZIP files listed in content/external.json.
  • Markdown Support: Renders Markdown with GitHub-style alert callouts (e.g., Note, Warning, Important).
  • Code Highlighting: Syntax highlighting for over 200 languages using Chroma.
  • Media + PDF Support: Automatically displays images, embeds videos, and includes a PDF viewer.
  • Recursive Sidebar + ZIP Downloads: Builds a file tree sidebar and emits a downloadable ZIP per project.
  • Single Binary Distribution: All HTML templates, CSS, and JS are embedded into the Go binary.

Getting Started

Prerequisites

  • Go 1.26 or later
  • Node.js (only for development/styling)

Installation

Clone the repository and build the binary:

go build -o static-repo main.go

Usage

Run the generator by specifying your content directory:

./static-repo -content ./my-docs -output ./dist

Typical content layout:

content/
  README.md                  # Optional overview page content
  external.json              # Optional external project list
  project-a/
    README.md                # Optional frontmatter: title/description/date
    docs/...
  project-b/
    README.md

The generator treats each subdirectory inside content/ as a project.

Flags

  • -content: Directory containing source files (default: content)
  • -output: Directory to write generated HTML (default: output)
  • -subdir: Subdirectory to prepend to the sidebar links (useful for hosting in a subpath)

Using content/external.json

If you want to include projects hosted elsewhere, create content/external.json with a JSON array of objects.

Each object supports:

  • url (required): Direct URL to a ZIP archive.
  • title (required): Display name shown on the overview page.
  • description (optional): Short summary shown on project cards.
  • date (optional): Date text shown on the overview page.

Example:

[
  {
    "url": "https://example.com/releases/my-project-docs.zip",
    "title": "My External Project",
    "description": "Documentation generated from another repository.",
    "date": "2026-03-10"
  },
  {
    "url": "https://example.com/downloads/legacy-docs.zip",
    "title": "Legacy Docs"
  }
]

Behavior notes:

  • External projects are downloaded during generation and merged into the same project overview.
  • The extracted ZIP content is rendered like local projects.
  • A temporary extraction directory is used and cleaned up automatically after generation.
  • The project URL slug for an external project is derived from title by lowercasing and replacing spaces with -.
  • If a ZIP download or extract fails, generation continues and logs a warning.

Frontmatter in README.md files

You can use YAML frontmatter at the top of README.md files to control page metadata.

Root content/README.md

The root content/README.md is rendered on the overview page (output/index.html).

Supported frontmatter keys:

  • title: Sets the overview page title.

Example:

---
title: Code
date: 2026-03-01
---

# Coding Projects

Note: only title is currently used for the overview page metadata; other keys are ignored there.

Project content/<project>/README.md

Each project directory can have its own README.md. Its frontmatter is used for project cards and page titles.

Supported frontmatter keys:

  • title: Display name for the project.
  • description: Summary shown on the overview card.
  • date: Date shown on the overview card.

Example:

---
title: Static Repo
description: Internal documentation and examples for the static site generator.
date: 2026-03-12
---

# Static Repo Docs

Development

  • make build-styles: Generates style.min.css using Tailwind CSS.
  • make generate: Runs the generator with default local paths.
  • make all: Builds styles and generates the site.

Modifying Templates

Templates and assets are located in internal/templates/templates/. Because they are embedded using embed.FS, you must re-build the Go binary after making changes to templates or CSS.

# Update styles
make build-styles
# Rebuild binary
go build -o static-repo main.go