Skip to content

CLAUDE.md

Latest commit

 

History

History
146 lines (104 loc) · 4.45 KB

CLAUDE.md

File metadata and controls

146 lines (104 loc) · 4.45 KB

CLAUDE.md

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

Project Overview

This is the documentation website for Capa (Cloud Application API) - a Mecha architecture-based multi-runtime SDK for Java applications. The site is built with Hugo using the Docsy theme and published to GitHub Pages.

Development Commands

Prerequisites

  • Hugo (extended version, v0.88.1+ recommended)
  • Node.js and npm (for PostCSS/Autoprefixer)
  • Git submodules (for Docsy theme)

Setup

# Initialize git submodules (required for Docsy theme)
git submodule update --init --recursive

# Install npm dependencies
npm install

Local Development

# Run Hugo development server
hugo server

# Run with draft content included
hugo server -D

# Run with live reload (default binds to localhost:1313)
hugo server --bind 0.0.0.0

Build

# Build the site (output goes to docs/ directory)
hugo --gc

# Build for production
HUGO_ENV="production" hugo --gc

Docker (Alternative)

# Run using Docker Compose
docker-compose up

# Or build and run manually
docker build -t capa-docs .
docker run -p 1313:1313 -v $(pwd):/src capa-docs server

Architecture

Hugo Configuration

  • Config file: config.toml
  • Theme: Docsy (git submodule at themes/docsy/)
  • Content directory: content/ (organized by language: zh/, en/)
  • Default content language: Chinese (zh)
  • Output directory: docs/ (configured for GitHub Pages)

Content Structure

Content is organized under content/zh/ and content/en/:

content/
├── zh/                          # Chinese content (default)
│   ├── _index.html             # Homepage
│   ├── docs/                   # Documentation
│   │   ├── Overview/           # Overview section
│   │   ├── GettingStarted/     # Getting started guides
│   │   ├── Concepts/           # Concept documentation
│   │   ├── Tasks/              # Task guides
│   │   ├── Examples/           # Examples
│   │   ├── Reference/          # API reference
│   │   └── ContributionGuidelines/
│   ├── blog/                   # Blog posts
│   ├── about/                  # About page
│   ├── community/              # Community page
│   └── search.md               # Search page
└── en/                         # English content (mirrors zh structure)

Key Configuration Details

  • Base URL: https://capa.rxcloud.group/
  • GitHub repo links: Point to https://github.com/capa-cloud/capa
  • Search: Uses Google Custom Search Engine (gcs_engine_id)
  • Syntax highlighting: Uses Chroma with "tango" style
  • Markdown engine: Goldmark with unsafe HTML enabled

Static Assets

  • Images: content/images/ or page bundles
  • Logo: Configure in assets/icons/logo.svg (navbar_logo is currently false)
  • Featured background: content/zh/featured-background.jpg

Deployment

The site is deployed to GitHub Pages via GitHub Actions (.github/workflows/deploy.yml):

  1. Push to master triggers the workflow
  2. Hugo builds the site with --gc --minify --destination docs
  3. peaceiris/actions-gh-pages@v3 deploys to the gh-pages branch
  4. Custom domain: capa.rxcloud.group (configured via static/CNAME)

Common Tasks

Adding New Documentation

  1. Create a new .md file in the appropriate section under content/zh/docs/
  2. Add front matter with title, description, and weight (for ordering)
  3. Create corresponding English version under content/en/docs/ if needed

Adding Blog Posts

  1. Create a new folder under content/zh/blog/ with an index.md file
  2. Use front matter with date, title, description, and author

Updating the Theme

# Update Docsy theme to latest version
git submodule update --remote --merge

Notes

  • The site uses a bilingual setup with Chinese as the default language
  • The docs/ directory contains the built site and should be regenerated with hugo --gc before committing
  • The Docsy theme is included as a git submodule - ensure it's initialized when cloning
  • Some feature images are generated by Hugo's image processing (stored in resources/)