Skip to content

Latest commit

 

History

History
76 lines (52 loc) · 4.13 KB

CLAUDE.md

File metadata and controls

76 lines (52 loc) · 4.13 KB

CLAUDE.md

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

Project Overview

This is getsaga.dev — the documentation website for Saga, a Swift static site generator. The site is itself built with Saga: it parses Saga's own source code and DocC files to produce documentation and API reference pages.

Commands

NEVER run just run — the dev server is always already running. Assume it is active and will pick up changes automatically.

All commands use just:

  • just run — development mode: compiles Tailwind CSS, copies DocC docs, generates symbol graph, then runs saga dev with file watching
  • just build — production build: same prep steps, then swift run to generate the site into deploy/
  • just compile — compile the Swift binary without running it
  • just resolve — resolve Swift Package Manager dependencies
  • just format — format code with swiftformat -swift-version 5 .
  • just clean — remove deploy/, .build/symbolgraph/, and content/docs/
  • just copy-docs — copy DocC markdown from Saga's checkout into content/docs/
  • just symbol-graph — generate Saga's symbol graph JSON for the API reference

Prerequisites: brew install loopwerk/tap/saga just

Architecture

Single executable target (Website) in Sources/Website/. The entry point is main.swift.

Build pipeline (main.swift)

  1. Tailwind CSS — compiles content/static/input.css → content/static/output.css via SwiftTailwind
  2. DocC rewriting — rewrites DocC-flavored markdown (Symbol, <doc:File>) into standard markdown with links to /api/ and /docs/ routes
  3. Guide documentation — registers content/docs/ folder, processes markdown through Parsley, Moon (syntax highlighting), and SwiftSoup (external links, TOC generation)
  4. API reference — loads .build/symbolgraph/Saga.symbols.json (generated by just symbol-graph), parses with SymbolKit, produces pages for each public type/function
  5. Static pages — landing page (index.html) and 404 page
  6. Post-processing — HTML minification via Bonsai (production only; skipped when isDev is true)

Key files

  • main.swift — orchestrates the entire build pipeline
  • Utils.swift — doc sorting order, DocC markdown rewriting (rewriteMarkdown), parameter/return value rendering
  • APIReference.swift — symbol graph parsing, declaration rendering, doc comment processing
  • DocProcessor.swift — item processors for guide pages (title cleanup, syntax highlighting, TOC, blockquote styling)
  • templates/Layout.swift — shared HTML layout with nav and footer
  • templates/HomePage.swift — landing page
  • templates/DocTemplate.swift — guide documentation page template
  • templates/APITemplate.swift — API reference page template

Content pipeline

The content/docs/ directory is generated (gitignored) — it's copied from Saga's DocC sources via just copy-docs, then rewritten in-place before Saga processes them. Do not edit these files directly.

The doc ordering is hardcoded in Utils.swift: ["index", "Installation", "GettingStarted", "Architecture", "AdvancedUsage"].

Code Style

  • SwiftFormat config in .swiftformat: 2-space indent, --indentcase true, --patternlet inline
  • Templates use Swim (imported as HTML) for type-safe HTML with Tailwind CSS classes
  • CSS is Tailwind v4, configured via content/static/input.css

Linux Compatibility

This project is deployed on Linux (via Docker). All Swift code must compile and run on Linux. Key things to watch for:

  • Foundation networking types (URLRequest, URLSession, etc.) require import FoundationNetworking on Linux. Use a conditional import: 
    #if canImport(FoundationNetworking)
  import FoundationNetworking
#endif
  • Avoid Apple-only APIs (e.g., Combine, SwiftUI, Objective-C runtime features). Stick to cross-platform Swift and Foundation.

Deployment

Multi-stage Docker build: Swift 6.0 builder → nginx:alpine serving deploy/. See Dockerfile and nginx.conf.