|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with |
| 4 | +code in this repository. |
| 5 | + |
| 6 | +## Project Overview |
| 7 | + |
| 8 | +This is the repository for the [Crossplane documentation](https://docs.crossplane.io). |
| 9 | +The documentation site is built using [Hugo](https://gohugo.io/) and hosted on |
| 10 | +Netlify. The site provides comprehensive documentation for Crossplane, a cloud |
| 11 | +native control plane framework. |
| 12 | + |
| 13 | +## Development Commands |
| 14 | + |
| 15 | +### Local Development |
| 16 | +- `hugo server` - Start local development server on http://localhost:1313 |
| 17 | +- `hugo server --minify` - Start server with minified output |
| 18 | +- `hugo --minify` - Build static site with minified output |
| 19 | + |
| 20 | +### Prerequisites |
| 21 | +- Hugo Extended version (required for SCSS/CSS processing) |
| 22 | +- Node.js and npm (for PostCSS processing) |
| 23 | +- Git (for content management) |
| 24 | +- Vale (for style linting) |
| 25 | + |
| 26 | +### Nix Development Environment |
| 27 | +For Nix users, a `shell.nix` file is provided with all necessary dependencies: |
| 28 | + |
| 29 | +```bash |
| 30 | +nix-shell # Enter development environment with Hugo, Vale, Node.js, and utilities |
| 31 | +``` |
| 32 | + |
| 33 | +The Nix shell includes: |
| 34 | +- Hugo (extended version) |
| 35 | +- Vale prose linter |
| 36 | +- Node.js 20 with npm |
| 37 | +- HTML validation tools |
| 38 | +- Image processing utilities (ImageMagick) |
| 39 | +- JSON/YAML processing tools (jq, yq) |
| 40 | + |
| 41 | +### Building and Deployment |
| 42 | +- Site automatically builds on Netlify using `netlify_build.sh` |
| 43 | +- Uses Hugo version 0.119.0 (specified in netlify.toml) |
| 44 | +- Production URL: https://docs.crossplane.io/ |
| 45 | +- Preview deployments available for PRs |
| 46 | + |
| 47 | +## Repository Structure |
| 48 | + |
| 49 | +### Content Organization |
| 50 | +- `content/` - All documentation content organized by version |
| 51 | + - `v1.18/`, `v1.19/`, `v1.20/` - Version-specific documentation |
| 52 | + - `master/` - Next release documentation |
| 53 | + - `v2.0-preview/` - Preview documentation for v2.0 |
| 54 | + - `contribute/` - Contributing guidelines and style guides |
| 55 | +- `static/` - Static assets (images, icons, etc.) |
| 56 | +- `themes/geekboot/` - Custom Hugo theme based on Geekdoc and Bootstrap |
| 57 | +- `utils/` - Development utilities (Vale style checking, webpack config) |
| 58 | + |
| 59 | +### Key Configuration Files |
| 60 | +- `config.yaml` - Hugo site configuration |
| 61 | +- `netlify.toml` - Netlify build and deployment configuration |
| 62 | +- `netlify_build.sh` - Custom build script for version management |
| 63 | +- `package.json` - PostCSS dependencies for CSS optimization |
| 64 | + |
| 65 | +## Documentation Architecture |
| 66 | + |
| 67 | +### Version Management |
| 68 | +- Each Crossplane version has its own content directory |
| 69 | +- Latest version (currently 1.20) is copied to `/latest` during build |
| 70 | +- Version dropdown menu allows switching between versions |
| 71 | +- Automatic redirects for EOL versions |
| 72 | + |
| 73 | +### Content Types |
| 74 | +- **Getting Started** - Installation and basic usage guides |
| 75 | +- **Concepts** - Core Crossplane concepts and architecture |
| 76 | +- **Guides** - How-to guides and advanced usage patterns |
| 77 | +- **API Reference** - CRD documentation generated from YAML |
| 78 | +- **CLI Reference** - Command reference documentation |
| 79 | + |
| 80 | +### Hugo Features Used |
| 81 | +- Custom shortcodes for enhanced functionality (tabs, hints, code highlighting) |
| 82 | +- Front matter for metadata (version, weight, state, descriptions) |
| 83 | +- Table of contents generation |
| 84 | +- Syntax highlighting with line numbers |
| 85 | +- Image optimization and processing |
| 86 | +- RSS feeds for sections |
| 87 | + |
| 88 | +## Writing Guidelines |
| 89 | + |
| 90 | +### Style Guide Essentials |
| 91 | +- Use active voice, avoid passive voice |
| 92 | +- Present tense, avoid "will" |
| 93 | +- Sentence-case headings |
| 94 | +- Wrap lines at 80 characters |
| 95 | +- Spell out numbers less than 10 |
| 96 | +- Use contractions (don't, can't, isn't) |
| 97 | +- No Oxford commas |
| 98 | +- U.S. English spelling and grammar |
| 99 | +- Capitalize "Crossplane" and "Kubernetes" (never "k8s") |
| 100 | + |
| 101 | +### Content Structure |
| 102 | +- Each page requires front matter with `title` and `weight` |
| 103 | +- Use `state: alpha` or `state: beta` for feature lifecycle |
| 104 | +- Include `alphaVersion` and `betaVersion` for feature tracking |
| 105 | +- Use descriptive link text, avoid "click here" |
| 106 | +- Order brand names alphabetically (AWS, Azure, GCP) |
| 107 | + |
| 108 | +### Code and Technical Content |
| 109 | +- Use inline code style (backticks) for files, directories, paths |
| 110 | +- Use angle brackets for placeholders (`<placeholder_name>`) |
| 111 | +- Kubernetes objects: use UpperCamelCase for Kinds, kebab-case for names |
| 112 | +- Use hover shortcodes to relate explanations to code examples |
| 113 | + |
| 114 | +## Development Workflow |
| 115 | + |
| 116 | +### Contributing Process |
| 117 | +1. Clone the repository: `git clone https://github.com/crossplane/docs.git` |
| 118 | +2. Set up development environment: |
| 119 | + - **With Nix**: Run `nix-shell` to enter development environment |
| 120 | + - **Without Nix**: Install Hugo Extended, Vale, and Node.js manually |
| 121 | +3. Run `hugo server` for local development |
| 122 | +4. Make changes to appropriate version directory in `/content` |
| 123 | +5. Test locally at http://localhost:1313 |
| 124 | +6. Run `vale content/` to check style compliance |
| 125 | +7. Submit PR for review |
| 126 | + |
| 127 | +### Content Management |
| 128 | +- Create new content as markdown files in appropriate version directories |
| 129 | +- Use `_index.md` for section landing pages |
| 130 | +- Include proper front matter for all pages |
| 131 | +- Test with Vale linter for style compliance |
| 132 | +- Images should be optimized and placed in appropriate directories |
| 133 | + |
| 134 | +### Quality Assurance |
| 135 | +- Vale linter enforces style guide compliance |
| 136 | +- HTML validation with htmltest |
| 137 | +- Automated Netlify preview deployments for all PRs |
| 138 | +- Manual review process for content accuracy |
| 139 | + |
| 140 | +## Build System Details |
| 141 | + |
| 142 | +### Hugo Configuration |
| 143 | +- Uses custom "geekboot" theme (based on Geekdoc + Bootstrap) |
| 144 | +- Goldmark renderer with unsafe HTML enabled |
| 145 | +- Syntax highlighting with line numbers and anchor links |
| 146 | +- Module mounts for content and asset processing |
| 147 | +- Table of contents generation (levels 1-9) |
| 148 | + |
| 149 | +### CSS and Assets |
| 150 | +- PostCSS with PurgeCSS for optimization |
| 151 | +- Custom SCSS in theme directory |
| 152 | +- Responsive design with Bootstrap framework |
| 153 | +- Font loading for Avenir and Consolas |
| 154 | +- Icon system with SVG assets |
| 155 | + |
| 156 | +### Netlify Integration |
| 157 | +- Environment-specific base URLs |
| 158 | +- Automatic redirects for moved/deprecated content |
| 159 | +- Build optimization with writeStats for PurgeCSS |
| 160 | +- Deploy preview URLs for testing |
| 161 | + |
| 162 | +## Common Tasks |
| 163 | + |
| 164 | +### Adding New Documentation |
| 165 | +1. Create markdown file in appropriate version directory |
| 166 | +2. Add front matter with title, weight, and optional state |
| 167 | +3. Follow style guide for writing |
| 168 | +4. Add to multiple versions if needed |
| 169 | +5. Test locally with Hugo server |
| 170 | + |
| 171 | +### Version Management |
| 172 | +- Copy content between version directories as needed |
| 173 | +- Update version references in netlify_build.sh |
| 174 | +- Ensure redirects are configured for moved content |
| 175 | +- Test version switching functionality |
| 176 | + |
| 177 | +### Style and Linting |
| 178 | +- Run Vale linter: `vale content/` |
| 179 | +- Check for style guide compliance |
| 180 | +- Validate HTML structure |
| 181 | +- Ensure proper image optimization |
| 182 | + |
| 183 | +## Important Files |
| 184 | + |
| 185 | +- `config.yaml` - Hugo site configuration and parameters |
| 186 | +- `netlify_build.sh` - Build script with version management logic |
| 187 | +- `shell.nix` - Nix development environment with all dependencies |
| 188 | +- `content/contribute/` - Comprehensive contributing guidelines |
| 189 | +- `themes/geekboot/layouts/` - Hugo templates and partials |
| 190 | +- `utils/vale/` - Vale style checking configuration |
| 191 | + |
| 192 | +## Vale Linting Guidelines |
| 193 | + |
| 194 | +**CRITICAL: The documentation uses Vale for strict style enforcement. ALL errors and warnings MUST be fixed before merging. Writing Vale-compliant content from the start saves significant time - fixing linting issues after writing is much more time-consuming than avoiding them initially.** |
| 195 | + |
| 196 | +Here are common issues to avoid: |
| 197 | + |
| 198 | +### Common Vale Errors |
| 199 | + |
| 200 | +**Spelling Issues:** |
| 201 | +- **API field names**: Put in backticks (`lastScheduleTime`) rather than adding to dictionaries |
| 202 | +- **Technical terms**: Add Crossplane-specific terms to `utils/vale/styles/Crossplane/crossplane-words.txt` |
| 203 | +- **General tech terms**: Add to `utils/vale/styles/Crossplane/allowed-jargon.txt` |
| 204 | +- **Hyphenated terms**: Add to `utils/vale/styles/Crossplane/spelling-exceptions.txt` |
| 205 | +- **Resource kinds**: When referring to Kubernetes resource kinds (Operation, CronOperation), these are correct - use Vale disable comments for false positives |
| 206 | + |
| 207 | +### Common Vale Warnings |
| 208 | + |
| 209 | +**Headings:** |
| 210 | +- Use sentence-case, not title-case: "How operations work" not "How Operations Work" |
| 211 | +- Exception: Technical terms like CronOperation in headings need disable comments |
| 212 | +- Use `<!-- vale Google.Headings = NO -->` around technical headings |
| 213 | + |
| 214 | +**Word Choice Issues:** |
| 215 | +- **Weasel words**: Avoid "many", "various", "numerous" → use "several", "multiple", "some" |
| 216 | +- **Too wordy**: "terminate" → "stop", "monitor" → "check" (unless monitoring is the correct technical term) |
| 217 | +- **Future tense**: "won't start" → "don't start", avoid "will" → use present tense |
| 218 | + |
| 219 | +**Passive Voice:** |
| 220 | +- "Operations are designed for" → "Operations focus on" |
| 221 | +- "may be terminated" → "may stop" |
| 222 | +- "being watched" → "under watch" |
| 223 | +- "is needed" → "you need" |
| 224 | + |
| 225 | +**Other Issues:** |
| 226 | +- **Ordinal numbers**: "1st" → "first" |
| 227 | +- **Adverbs**: Remove "gracefully", "correctly", "properly", "repeatedly" |
| 228 | +- **Contractions**: Use "can't" instead of "cannot" |
| 229 | + |
| 230 | +### Vale Disable Comments |
| 231 | + |
| 232 | +Use disable comments for legitimate technical terms that trigger false positives: |
| 233 | + |
| 234 | +```markdown |
| 235 | +<!-- vale Google.Headings = NO --> |
| 236 | +### CronOperation |
| 237 | +<!-- vale Google.Headings = YES --> |
| 238 | + |
| 239 | +<!-- vale write-good.TooWordy = NO --> |
| 240 | +Monitor resource usage carefully. |
| 241 | +<!-- vale write-good.TooWordy = YES --> |
| 242 | +``` |
| 243 | + |
| 244 | +### Dictionary Management |
| 245 | + |
| 246 | +- **`crossplane-words.txt`**: Crossplane-specific terms only (CronOperation, XRD, etc.) |
| 247 | +- **`allowed-jargon.txt`**: General technical terms (kubectl, ConfigMap, etc.) |
| 248 | +- **`spelling-exceptions.txt`**: Hyphenated terms (day-two, self-signed, etc.) |
| 249 | +- Keep all dictionaries sorted alphabetically |
| 250 | + |
| 251 | +### Testing Vale |
| 252 | + |
| 253 | +**ALWAYS run Vale before considering documentation complete:** |
| 254 | + |
| 255 | +```bash |
| 256 | +# Check only warnings and errors (ignore suggestions) |
| 257 | +vale --minAlertLevel=warning content/ |
| 258 | + |
| 259 | +# Get structured output for analysis |
| 260 | +vale --output=JSON content/ | jq '.[][] | select(.Severity == "warning")' |
| 261 | +``` |
| 262 | + |
| 263 | +**Remember: Writing documentation that follows these guidelines from the start is much faster than writing first and fixing Vale issues later. The time investment in learning these patterns pays off immediately.** |
| 264 | + |
| 265 | +## Session Management |
| 266 | + |
| 267 | +- **Pre-Compaction Analysis**: Before compacting chat history, provide a |
| 268 | + structured session summary including: |
| 269 | + - Documentation updates made and their impact |
| 270 | + - Important learnings about Hugo, documentation patterns, or writing guidelines |
| 271 | + - Potential updates to CLAUDE.md based on new documentation features or workflows |
| 272 | + - Any recurring style or technical issues encountered |
0 commit comments