mirror of
https://github.com/jimeh/commonflow.org.git
synced 2026-02-19 05:46:40 +00:00
88 lines
2.7 KiB
Markdown
88 lines
2.7 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
```
|
|
|
|
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
|
|
- **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
|
|
- `icons/GitHubIcon.astro` - GitHub SVG icon
|
|
- `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
|
|
|
|
1. Add new version to `versions` array in `src/config.ts`
|
|
2. Update `currentVersion` if this is the new default
|
|
3. Run `bun run update` to fetch specs from GitHub
|
|
4. Run `bun run build` to rebuild the site
|