155 lines
5.0 KiB
Markdown
155 lines
5.0 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
# 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
|
|
```bash
|
|
# 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`
|