linkbeam/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

LinkBeam is a static site generator for creating personal link-in-bio pages (similar to Linktree). It reads a YAML configuration file containing user profile information, links, and social media, then generates a themed HTML page using Go templates.

CI/CD Pipeline

The project uses Gitea Actions for continuous integration and deployment.

Workflows

1. CI Pipeline (.gitea/workflows/ci.yml):

   • Runs on push to main/develop and pull requests
   • Lint: golangci-lint, go fmt, go vet
   • Test: Run tests with race detection and coverage
   • Build: Multi-platform builds (Linux, Windows, macOS) for amd64, 386, arm64, armv7
   • Docker: Build multi-arch Docker images

2. Docker Publish (.gitea/workflows/docker-publish.yml):

   • Triggered on version tags (v*)
   • Builds and pushes Docker images to container registry
   • Multi-architecture: linux/amd64, linux/arm64, linux/arm/v7

3. Release (.gitea/workflows/release.yml):

   • Triggered on semver tags (v*..)
   • Creates GitHub/Gitea releases with binaries for all platforms
   • Generates SHA256 checksums for verification

Local Testing

# Check version
./linkbeam -v
# or: ./linkbeam --version

# Test Docker build
docker build -t linkbeam:test .

# Run Docker container
docker run -v $(pwd)/config.yaml:/app/config/config.yaml \
           -v $(pwd)/dist:/app/dist \
           linkbeam:test

# Test with docker-compose
docker-compose up

Development Commands

Pre-commit Setup

This project uses pre-commit hooks for code quality. First-time setup:

# Install pre-commit hooks
make install-hooks
# or: pre-commit install

# Run all hooks manually
make pre-commit
# or: pre-commit run --all-files

The hooks automatically run on commit and check: go fmt, goimports, go vet, golangci-lint, go test, go mod tidy, YAML syntax, and more.

Building and Running

# Build binary (outputs to dist/linkbeam)
make build
# or: go build -o dist/linkbeam cmd/linkbeam/main.go

# Run with example config
make run-example
# or: go run cmd/linkbeam/main.go --config internal/config/testdata/config.yaml

# Run with custom config (long flags)
./linkbeam --config config.yaml --template templates/base.html --output dist/index.html

# Run with custom config (short flags)
./linkbeam -c config.yaml -t templates/base.html -o dist/index.html

# Run all tests
make test
# or: go test -v ./...

# Run tests for a specific package
go test ./internal/config
go test ./internal/generator

# Run a single test function
go test -v -run TestLoad ./internal/config

# Clean build artifacts
make clean

CLI Options

• -c, --config: Path to config YAML file (default: "config.yaml")
• -t, --template: Path to HTML template (default: "templates/base.html")
• -o, --output: Path to output HTML file (default: "dist/index.html")
• -v, --version: Print version information

Output

The dist/ directory contains both build artifacts and generated site:

• dist/linkbeam - Compiled binary
• dist/index.html - Main HTML page
• dist/themes/ - Copied CSS theme files

Architecture

Two-Layer Structure

1. Config Layer (internal/config/):

   • Loads and validates YAML configuration files
   • Defines data structures: Config, Link, Social
   • Validates theme (must be "light" or "dark") and required fields (name cannot be empty)
   • Config validation happens automatically during config.Load()

2. Generator Layer (internal/generator/):

   • HTML Generation: Orchestrates template rendering using Go's html/template
     • GenerateSite(cfg, templatePath, outPath) - Creates HTML from templates
   • Asset Management: Copies CSS themes and static files to output directory
     • CopyAssets(distDir, themeDirs...) - Copies theme files to dist/themes/
   • Text Rendering: Plain-text representation for debugging
     • RenderUserPage(cfg) - Returns text-based preview of the page

Configuration Format

The config YAML structure in internal/config/testdata/config.yaml:

• name: User's display name (required)
• bio: Short biography text
• avatar: Path to avatar image
• theme: "light" or "dark" (validated)
• links[]: Array of link objects with title, url, icon
• socials[]: Array of social media links with platform, url, icon

Templates

Templates in templates/ use Go template syntax:

• base.html: Main page template with theme support (data-theme="{{ .Theme }}")
• Template receives the entire Config struct as data
• Access config fields with {{ .Name }}, {{ .Bio }}, etc.
• Iterate over links with {{- range .Links }}

Testing Strategy

• Tests use table-driven patterns and dependency injection
• cmd/linkbeam/main_test.go: Mocks the config loader and captures stdout
• Config tests validate YAML parsing and business rules
• Generator tests verify file creation and template execution
• All tests use the testdata in internal/config/testdata/config.yaml