CLAUDE.md

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

Project Overview

This is the source for commonflow.org, an Astro-based static site that documents the Git Common-Flow specification. Common-Flow is a git workflow specification that combines GitHub Flow with versioned releases.

Build Commands

# Install tooling (bun) via mise
mise install

# Install dependencies
bun install

# Development server
bun run dev

# Build site (outputs to docs/ directory)
bun run build

# Preview built site
bun run preview

# Type checking
bun run check

# Linting
bun run lint

# Formatting
bun run format
bun run format:check

# Update specs from upstream (fetches from github.com/jimeh/common-flow)
bun run update-specs

The site is built to docs/ for GitHub Pages hosting.

Architecture

Astro 5.x static site generator
Tailwind CSS 4.x for styling with dark mode support
astro-icon with Heroicons and Simple Icons for icons
Content Collections for spec markdown files
TypeScript throughout
Bun as JavaScript runtime and package manager (managed via mise)

Key Files

src/config.ts - Site configuration with version list
src/content.config.ts - Astro content collection definition
src/layouts/BaseLayout.astro - Base layout with head, meta tags, theme scripts
src/layouts/SpecLayout.astro - Spec page layout composing all sections
src/components/ - UI components:
- Header.astro - Site header with navigation
- Footer.astro - Site footer
- Hero.astro - Landing page hero section
- AboutSection.astro - About Common-Flow section
- FAQSection.astro - FAQ section
- SectionHeader.astro - Reusable section header (title + subtitle)
- SpecSection.astro - Spec section with terminology and specification
- SpecSidebar.astro - Spec page table of contents sidebar
- TocLink.astro - Reusable TOC link component
- ThemeToggle.astro - Dark/light mode toggle
- VersionSelector.astro - Spec version dropdown
src/scripts/activeSectionTracker.ts - Shared scroll-based active section tracking
src/pages/index.astro - Landing page
src/pages/404.astro - 404 error page
src/pages/spec/[version].astro - Dynamic route for spec versions
src/utils/parseSpecContent.ts - Markdown parsing utilities
src/content/spec/*.md - Versioned spec documents
public/spec/*.svg - SVG diagrams for each version
scripts/update-specs.ts - Fetches specs from GitHub

Updating Spec Versions

Add new version to versions array in src/config.ts
Update currentVersion if this is the new default
Run bun run update to fetch specs from GitHub
Run bun run build to rebuild the site

2.7 KiB Raw Blame History