|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Project Overview |
| 6 | + |
| 7 | +This is a Hugo-based static website focused on Spec Coding, Spec Driven Development, and Agentic AI Software Development Tools. The site is published to GitHub Pages and uses the hugo-clarity theme. |
| 8 | + |
| 9 | +**Site URLs:** |
| 10 | +- Production: https://specoding.com/ |
| 11 | +- Alternate: https://www.specoding.com |
| 12 | + |
| 13 | +**Author:** Tony Kay (@cloud_assembler on X) |
| 14 | + |
| 15 | +## Hugo Commands |
| 16 | + |
| 17 | +### Development |
| 18 | +```bash |
| 19 | +# Start local development server with drafts |
| 20 | +hugo server -D |
| 21 | + |
| 22 | +# Start server without drafts |
| 23 | +hugo server |
| 24 | + |
| 25 | +# Start server and watch for changes |
| 26 | +hugo server --watch |
| 27 | +``` |
| 28 | + |
| 29 | +### Building |
| 30 | +```bash |
| 31 | +# Build the site (output to ./public) |
| 32 | +hugo |
| 33 | + |
| 34 | +# Build with garbage collection and minification (production-ready) |
| 35 | +hugo --gc --minify |
| 36 | + |
| 37 | +# Build for specific baseURL |
| 38 | +hugo --baseURL "https://specoding.com/" |
| 39 | +``` |
| 40 | + |
| 41 | +### Content Management |
| 42 | +```bash |
| 43 | +# Create new post using default archetype |
| 44 | +hugo new content/post/my-new-post.md |
| 45 | + |
| 46 | +# Create content with specific archetype |
| 47 | +hugo new --kind post content/post/my-post.md |
| 48 | +``` |
| 49 | + |
| 50 | +## Architecture |
| 51 | + |
| 52 | +### Configuration Structure |
| 53 | + |
| 54 | +The site uses Hugo's modular configuration approach with split config files in `config/_default/`: |
| 55 | + |
| 56 | +- **hugo.toml**: Base Hugo settings, theme selection, taxonomies, outputs |
| 57 | +- **config.toml**: Site metadata, baseURL, security settings, cache configuration |
| 58 | +- **params.toml**: Theme-specific parameters (hugo-clarity settings), analytics, author info |
| 59 | +- **languages.toml**: Language configuration (currently English only, title: "AI Assembler") |
| 60 | +- **menus/menu.en.toml**: Navigation menu definitions |
| 61 | + |
| 62 | +**Important Configuration Notes:** |
| 63 | +- Theme is loaded as a git submodule at `themes/hugo-clarity` |
| 64 | +- `baseurl` must include trailing slash for share icons to work properly |
| 65 | +- Hugo caches images to `:cacheDir/images` for GitHub Pages compatibility |
| 66 | +- Extended Hugo version required for Dart Sass compilation |
| 67 | + |
| 68 | +### Theme: Hugo Clarity |
| 69 | + |
| 70 | +The site uses the hugo-clarity theme (https://github.com/chipzoller/hugo-clarity) installed as a git submodule. Key theme settings: |
| 71 | + |
| 72 | +- **Page Bundles**: Enabled (`usePageBundles = true`) - assets grouped with posts as leaf bundles |
| 73 | +- **Search**: Enabled with JSON output format |
| 74 | +- **Code Display**: Max 7 lines with line numbers enabled, scrollable/expandable |
| 75 | +- **Main Sections**: Posts located in `content/post/` |
| 76 | +- **Logo**: `images/spec-coding-logo.png` |
| 77 | +- **Fallback OG Image**: `images/thumbnail.png` |
| 78 | + |
| 79 | +### Directory Structure |
| 80 | + |
| 81 | +``` |
| 82 | +. |
| 83 | +├── archetypes/ # Content templates for hugo new command |
| 84 | +├── assets/ # Source files processed by Hugo Pipes (currently empty) |
| 85 | +├── config/_default/ # Modular configuration files |
| 86 | +├── content/ # Site content (posts, pages) - currently minimal |
| 87 | +│ └── images/ # Content images |
| 88 | +├── data/ # Data files for site generation |
| 89 | +├── i18n/ # Internationalization files |
| 90 | +├── layouts/ # Custom layout overrides (currently empty, using theme defaults) |
| 91 | +├── public/ # Generated site output (git-tracked for GitHub Pages) |
| 92 | +├── resources/ # Cached processed resources |
| 93 | +├── static/ # Static files copied as-is to output |
| 94 | +└── themes/hugo-clarity/ # Theme git submodule |
| 95 | +``` |
| 96 | + |
| 97 | +### Content Organization |
| 98 | + |
| 99 | +- **Posts**: Located in `content/post/` directory |
| 100 | +- **Taxonomies**: Categories, tags, series, and authors |
| 101 | +- **Page Bundles**: Content can be organized as leaf bundles with co-located assets |
| 102 | +- **Drafts**: Marked with `draft = true` in front matter |
| 103 | + |
| 104 | +### Deployment |
| 105 | + |
| 106 | +**GitHub Actions Workflow** (`.github/workflows/hugo.yaml`): |
| 107 | +- Triggers on push to `main` branch or manual workflow dispatch |
| 108 | +- Environment versions: |
| 109 | + - Hugo: 0.151.0 (extended) |
| 110 | + - Dart Sass: 1.93.2 |
| 111 | + - Go: 1.25.1 |
| 112 | + - Node.js: 22.18.0 |
| 113 | +- Build process: Checkout with submodules → Install dependencies → Build with `--gc --minify` → Deploy to GitHub Pages |
| 114 | +- Uses Hugo cache for faster builds |
| 115 | +- Deploys `./public` directory to GitHub Pages |
| 116 | + |
| 117 | +### Spec-Kit Integration |
| 118 | + |
| 119 | +This project uses Spec-Kit for specification-driven development with custom slash commands in `.claude/commands/`: |
| 120 | + |
| 121 | +- `/speckit.specify` - Create/update feature specifications |
| 122 | +- `/speckit.plan` - Execute implementation planning workflow |
| 123 | +- `/speckit.tasks` - Generate actionable dependency-ordered tasks |
| 124 | +- `/speckit.implement` - Execute implementation plan |
| 125 | +- `/speckit.analyze` - Cross-artifact consistency analysis |
| 126 | +- `/speckit.clarify` - Identify underspecified areas |
| 127 | +- `/speckit.checklist` - Generate custom feature checklists |
| 128 | +- `/speckit.constitution` - Manage project constitution |
| 129 | + |
| 130 | +Templates and scripts located in `.specify/`. |
| 131 | + |
| 132 | +## Working with Themes |
| 133 | + |
| 134 | +The hugo-clarity theme is a git submodule. To update the theme: |
| 135 | + |
| 136 | +```bash |
| 137 | +cd themes/hugo-clarity |
| 138 | +git pull origin main |
| 139 | +cd ../.. |
| 140 | +git add themes/hugo-clarity |
| 141 | +git commit -m "Update hugo-clarity theme" |
| 142 | +``` |
| 143 | + |
| 144 | +**Customization Approach:** |
| 145 | +- Override theme templates by creating matching files in `layouts/` |
| 146 | +- Override theme assets by creating matching files in `assets/` |
| 147 | +- Theme-specific settings controlled via `config/_default/params.toml` |
| 148 | + |
| 149 | +## Content Guidelines |
| 150 | + |
| 151 | +When creating new posts: |
| 152 | +1. Use `hugo new content/post/post-name.md` to ensure proper front matter |
| 153 | +2. Include these front matter fields: `title`, `date`, `draft`, `tags`, `categories` |
| 154 | +3. Set `draft = false` when ready to publish |
| 155 | +4. Consider using page bundles for posts with multiple images or assets |
| 156 | + |
| 157 | +## Local Development Notes |
| 158 | + |
| 159 | +- Local Hugo version: v0.151.0+extended+withdeploy (darwin/arm64, installed via brew) |
| 160 | +- The `./public` directory is tracked in git for GitHub Pages deployment |
| 161 | +- Always test builds locally with `hugo --gc --minify` before pushing |
| 162 | +- Check that submodules are initialized: `git submodule update --init --recursive` |
0 commit comments