mirror of https://github.com/crossplane/docs.git
Remove CLAUDE stuff
Committed by accident. Signed-off-by: Nic Cope <nicc@rk0n.org>
This commit is contained in:
Nic Cope
parent
f75fb54d6c
commit
334576410e
|
|
@ -1,55 +0,0 @@
|
|||
{
|
||||
"$schema": "https://json.schemastore.org/claude-code-settings.json",
|
||||
"permissions": {
|
||||
"allow": [
|
||||
"Bash(find:*)",
|
||||
"Bash(nix-shell:*)",
|
||||
"Bash(vale:*)",
|
||||
"Bash(grep:*)",
|
||||
"Bash(git add:*)",
|
||||
"Bash(git commit:*)",
|
||||
"Bash(for file in /home/negz/control/crossplane/docs/content/v1.{18,19,20}/learn/feature-lifecycle.md)",
|
||||
"Bash(do sed -i 's/won''''t be/aren''''t/g; s/will provide/provide/g' \"$file\")",
|
||||
"Bash(done)",
|
||||
"Bash(for file in /home/negz/control/crossplane/docs/content/v1.{18,19,20}/learn/release-cycle.md)",
|
||||
"Bash(do sed -i 's/will be/are/g; s/won''''t be/aren''''t/g; s/will /\\0/g' \"$file\")",
|
||||
"Bash(sed:*)",
|
||||
"Bash(for version in v1.18 v1.19 v1.20)",
|
||||
"Bash(do)",
|
||||
"Bash(for file in /home/negz/control/crossplane/docs/content/$version/learn/release-cycle.md)",
|
||||
"Bash(if [[ -f \"$file\" ]])",
|
||||
"Bash(then)",
|
||||
"Bash(fi)",
|
||||
"Bash(for file in /home/negz/control/crossplane/docs/content/$version/guides/vault-injection.md)",
|
||||
"Bash(for:*)",
|
||||
"Bash(# Fix specific line-by-line issues in remaining files\nsed -i ''132s/will assign/assigns/'' /home/negz/control/crossplane/docs/content/v1.19/concepts/composition-revisions.md\nsed -i ''329s/will also/also/'' /home/negz/control/crossplane/docs/content/v1.19/concepts/composition-revisions.md\nsed -i ''294s/will automatically/automatically/'' /home/negz/control/crossplane/docs/content/v1.19/concepts/packages.md\nsed -i ''317s/will automatically/automatically/'' /home/negz/control/crossplane/docs/content/v1.19/concepts/providers.md\n\nsed -i ''132s/will assign/assigns/'' /home/negz/control/crossplane/docs/content/v1.20/concepts/composition-revisions.md\nsed -i ''329s/will also/also/'' /home/negz/control/crossplane/docs/content/v1.20/concepts/composition-revisions.md\nsed -i ''84s/will select/selects/'' /home/negz/control/crossplane/docs/content/v1.20/concepts/composition-revisions.md\nsed -i ''19s/will enforce/enforces/'' /home/negz/control/crossplane/docs/content/v1.20/guides/change-logs.md\n\nsed -i ''84s/will select/selects/'' /home/negz/control/crossplane/docs/content/v2.0-preview/composition/composition-revisions.md\nsed -i ''128s/will assign/assigns/'' /home/negz/control/crossplane/docs/content/v2.0-preview/composition/composition-revisions.md\nsed -i ''314s/will also/also/'' /home/negz/control/crossplane/docs/content/v2.0-preview/composition/composition-revisions.md\nsed -i ''293s/will automatically/automatically/'' /home/negz/control/crossplane/docs/content/v2.0-preview/packages/configurations.md\nsed -i ''317s/will automatically/automatically/'' /home/negz/control/crossplane/docs/content/v2.0-preview/packages/providers.md)",
|
||||
"Bash(rg:*)",
|
||||
"Bash(do sed -i 's/a large number of CRDs/many CRDs/g' \"content/$file/guides/crossplane-with-argo-cd.md\")",
|
||||
"Bash(/dev/null)",
|
||||
"Bash(hugo:*)",
|
||||
"Bash(jq:*)",
|
||||
"Bash(gh pr view:*)",
|
||||
"Bash(gh pr diff:*)",
|
||||
"WebFetch(domain:raw.githubusercontent.com)",
|
||||
"Bash(htmltest:*)",
|
||||
"WebFetch(domain:protobuf.dev)",
|
||||
"WebFetch(domain:googleapis.dev)",
|
||||
"Bash(mkdir:*)",
|
||||
"Bash(mv:*)",
|
||||
"Bash(true)",
|
||||
"Bash(crossplane alpha render:*)",
|
||||
"Bash(md5sum:*)",
|
||||
"Bash(cp:*)",
|
||||
"Bash(kubectl apply:*)",
|
||||
"Bash(kubectl get:*)",
|
||||
"Bash(kubectl describe:*)",
|
||||
"Bash(kubectl delete:*)",
|
||||
"Bash(/tmp/crank-fixed:*)",
|
||||
"WebFetch(domain:github.com)",
|
||||
"Bash(gh api:*)"
|
||||
],
|
||||
"additionalDirectories": [
|
||||
"/home/negz/control/crossplane/crossplane"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -84,3 +84,7 @@ jekyll_files/*
|
|||
# Ignore htmltest generated /tmp folder
|
||||
######################
|
||||
tmp/*
|
||||
|
||||
# AI stuff
|
||||
CLAUDE.md
|
||||
.claude
|
||||
|
|
|
|||
272
CLAUDE.md
272
CLAUDE.md
|
|
@ -1,272 +0,0 @@
|
|||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with
|
||||
code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
This is the repository for the [Crossplane documentation](https://docs.crossplane.io).
|
||||
The documentation site is built using [Hugo](https://gohugo.io/) and hosted on
|
||||
Netlify. The site provides comprehensive documentation for Crossplane, a cloud
|
||||
native control plane framework.
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Local Development
|
||||
- `hugo server` - Start local development server on http://localhost:1313
|
||||
- `hugo server --minify` - Start server with minified output
|
||||
- `hugo --minify` - Build static site with minified output
|
||||
|
||||
### Prerequisites
|
||||
- Hugo Extended version (required for SCSS/CSS processing)
|
||||
- Node.js and npm (for PostCSS processing)
|
||||
- Git (for content management)
|
||||
- Vale (for style linting)
|
||||
|
||||
### Nix Development Environment
|
||||
For Nix users, a `shell.nix` file is provided with all necessary dependencies:
|
||||
|
||||
```bash
|
||||
nix-shell # Enter development environment with Hugo, Vale, Node.js, and utilities
|
||||
```
|
||||
|
||||
The Nix shell includes:
|
||||
- Hugo (extended version)
|
||||
- Vale prose linter
|
||||
- Node.js 20 with npm
|
||||
- HTML validation tools
|
||||
- Image processing utilities (ImageMagick)
|
||||
- JSON/YAML processing tools (jq, yq)
|
||||
|
||||
### Building and Deployment
|
||||
- Site automatically builds on Netlify using `netlify_build.sh`
|
||||
- Uses Hugo version 0.119.0 (specified in netlify.toml)
|
||||
- Production URL: https://docs.crossplane.io/
|
||||
- Preview deployments available for PRs
|
||||
|
||||
## Repository Structure
|
||||
|
||||
### Content Organization
|
||||
- `content/` - All documentation content organized by version
|
||||
- `v1.18/`, `v1.19/`, `v1.20/` - Version-specific documentation
|
||||
- `master/` - Next release documentation
|
||||
- `v2.0-preview/` - Preview documentation for v2.0
|
||||
- `contribute/` - Contributing guidelines and style guides
|
||||
- `static/` - Static assets (images, icons, etc.)
|
||||
- `themes/geekboot/` - Custom Hugo theme based on Geekdoc and Bootstrap
|
||||
- `utils/` - Development utilities (Vale style checking, webpack config)
|
||||
|
||||
### Key Configuration Files
|
||||
- `config.yaml` - Hugo site configuration
|
||||
- `netlify.toml` - Netlify build and deployment configuration
|
||||
- `netlify_build.sh` - Custom build script for version management
|
||||
- `package.json` - PostCSS dependencies for CSS optimization
|
||||
|
||||
## Documentation Architecture
|
||||
|
||||
### Version Management
|
||||
- Each Crossplane version has its own content directory
|
||||
- Latest version (currently 1.20) is copied to `/latest` during build
|
||||
- Version dropdown menu allows switching between versions
|
||||
- Automatic redirects for EOL versions
|
||||
|
||||
### Content Types
|
||||
- **Getting Started** - Installation and basic usage guides
|
||||
- **Concepts** - Core Crossplane concepts and architecture
|
||||
- **Guides** - How-to guides and advanced usage patterns
|
||||
- **API Reference** - CRD documentation generated from YAML
|
||||
- **CLI Reference** - Command reference documentation
|
||||
|
||||
### Hugo Features Used
|
||||
- Custom shortcodes for enhanced functionality (tabs, hints, code highlighting)
|
||||
- Front matter for metadata (version, weight, state, descriptions)
|
||||
- Table of contents generation
|
||||
- Syntax highlighting with line numbers
|
||||
- Image optimization and processing
|
||||
- RSS feeds for sections
|
||||
|
||||
## Writing Guidelines
|
||||
|
||||
### Style Guide Essentials
|
||||
- Use active voice, avoid passive voice
|
||||
- Present tense, avoid "will"
|
||||
- Sentence-case headings
|
||||
- Wrap lines at 80 characters
|
||||
- Spell out numbers less than 10
|
||||
- Use contractions (don't, can't, isn't)
|
||||
- No Oxford commas
|
||||
- U.S. English spelling and grammar
|
||||
- Capitalize "Crossplane" and "Kubernetes" (never "k8s")
|
||||
|
||||
### Content Structure
|
||||
- Each page requires front matter with `title` and `weight`
|
||||
- Use `state: alpha` or `state: beta` for feature lifecycle
|
||||
- Include `alphaVersion` and `betaVersion` for feature tracking
|
||||
- Use descriptive link text, avoid "click here"
|
||||
- Order brand names alphabetically (AWS, Azure, GCP)
|
||||
|
||||
### Code and Technical Content
|
||||
- Use inline code style (backticks) for files, directories, paths
|
||||
- Use angle brackets for placeholders (`<placeholder_name>`)
|
||||
- Kubernetes objects: use UpperCamelCase for Kinds, kebab-case for names
|
||||
- Use hover shortcodes to relate explanations to code examples
|
||||
|
||||
## Development Workflow
|
||||
|
||||
### Contributing Process
|
||||
1. Clone the repository: `git clone https://github.com/crossplane/docs.git`
|
||||
2. Set up development environment:
|
||||
- **With Nix**: Run `nix-shell` to enter development environment
|
||||
- **Without Nix**: Install Hugo Extended, Vale, and Node.js manually
|
||||
3. Run `hugo server` for local development
|
||||
4. Make changes to appropriate version directory in `/content`
|
||||
5. Test locally at http://localhost:1313
|
||||
6. Run `vale content/` to check style compliance
|
||||
7. Submit PR for review
|
||||
|
||||
### Content Management
|
||||
- Create new content as markdown files in appropriate version directories
|
||||
- Use `_index.md` for section landing pages
|
||||
- Include proper front matter for all pages
|
||||
- Test with Vale linter for style compliance
|
||||
- Images should be optimized and placed in appropriate directories
|
||||
|
||||
### Quality Assurance
|
||||
- Vale linter enforces style guide compliance
|
||||
- HTML validation with htmltest
|
||||
- Automated Netlify preview deployments for all PRs
|
||||
- Manual review process for content accuracy
|
||||
|
||||
## Build System Details
|
||||
|
||||
### Hugo Configuration
|
||||
- Uses custom "geekboot" theme (based on Geekdoc + Bootstrap)
|
||||
- Goldmark renderer with unsafe HTML enabled
|
||||
- Syntax highlighting with line numbers and anchor links
|
||||
- Module mounts for content and asset processing
|
||||
- Table of contents generation (levels 1-9)
|
||||
|
||||
### CSS and Assets
|
||||
- PostCSS with PurgeCSS for optimization
|
||||
- Custom SCSS in theme directory
|
||||
- Responsive design with Bootstrap framework
|
||||
- Font loading for Avenir and Consolas
|
||||
- Icon system with SVG assets
|
||||
|
||||
### Netlify Integration
|
||||
- Environment-specific base URLs
|
||||
- Automatic redirects for moved/deprecated content
|
||||
- Build optimization with writeStats for PurgeCSS
|
||||
- Deploy preview URLs for testing
|
||||
|
||||
## Common Tasks
|
||||
|
||||
### Adding New Documentation
|
||||
1. Create markdown file in appropriate version directory
|
||||
2. Add front matter with title, weight, and optional state
|
||||
3. Follow style guide for writing
|
||||
4. Add to multiple versions if needed
|
||||
5. Test locally with Hugo server
|
||||
|
||||
### Version Management
|
||||
- Copy content between version directories as needed
|
||||
- Update version references in netlify_build.sh
|
||||
- Ensure redirects are configured for moved content
|
||||
- Test version switching functionality
|
||||
|
||||
### Style and Linting
|
||||
- Run Vale linter: `vale content/`
|
||||
- Check for style guide compliance
|
||||
- Validate HTML structure
|
||||
- Ensure proper image optimization
|
||||
|
||||
## Important Files
|
||||
|
||||
- `config.yaml` - Hugo site configuration and parameters
|
||||
- `netlify_build.sh` - Build script with version management logic
|
||||
- `shell.nix` - Nix development environment with all dependencies
|
||||
- `content/contribute/` - Comprehensive contributing guidelines
|
||||
- `themes/geekboot/layouts/` - Hugo templates and partials
|
||||
- `utils/vale/` - Vale style checking configuration
|
||||
|
||||
## Vale Linting Guidelines
|
||||
|
||||
**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.**
|
||||
|
||||
Here are common issues to avoid:
|
||||
|
||||
### Common Vale Errors
|
||||
|
||||
**Spelling Issues:**
|
||||
- **API field names**: Put in backticks (`lastScheduleTime`) rather than adding to dictionaries
|
||||
- **Technical terms**: Add Crossplane-specific terms to `utils/vale/styles/Crossplane/crossplane-words.txt`
|
||||
- **General tech terms**: Add to `utils/vale/styles/Crossplane/allowed-jargon.txt`
|
||||
- **Hyphenated terms**: Add to `utils/vale/styles/Crossplane/spelling-exceptions.txt`
|
||||
- **Resource kinds**: When referring to Kubernetes resource kinds (Operation, CronOperation), these are correct - use Vale disable comments for false positives
|
||||
|
||||
### Common Vale Warnings
|
||||
|
||||
**Headings:**
|
||||
- Use sentence-case, not title-case: "How operations work" not "How Operations Work"
|
||||
- Exception: Technical terms like CronOperation in headings need disable comments
|
||||
- Use `<!-- vale Google.Headings = NO -->` around technical headings
|
||||
|
||||
**Word Choice Issues:**
|
||||
- **Weasel words**: Avoid "many", "various", "numerous" → use "several", "multiple", "some"
|
||||
- **Too wordy**: "terminate" → "stop", "monitor" → "check" (unless monitoring is the correct technical term)
|
||||
- **Future tense**: "won't start" → "don't start", avoid "will" → use present tense
|
||||
|
||||
**Passive Voice:**
|
||||
- "Operations are designed for" → "Operations focus on"
|
||||
- "may be terminated" → "may stop"
|
||||
- "being watched" → "under watch"
|
||||
- "is needed" → "you need"
|
||||
|
||||
**Other Issues:**
|
||||
- **Ordinal numbers**: "1st" → "first"
|
||||
- **Adverbs**: Remove "gracefully", "correctly", "properly", "repeatedly"
|
||||
- **Contractions**: Use "can't" instead of "cannot"
|
||||
|
||||
### Vale Disable Comments
|
||||
|
||||
Use disable comments for legitimate technical terms that trigger false positives:
|
||||
|
||||
```markdown
|
||||
<!-- vale Google.Headings = NO -->
|
||||
### CronOperation
|
||||
<!-- vale Google.Headings = YES -->
|
||||
|
||||
<!-- vale write-good.TooWordy = NO -->
|
||||
Monitor resource usage carefully.
|
||||
<!-- vale write-good.TooWordy = YES -->
|
||||
```
|
||||
|
||||
### Dictionary Management
|
||||
|
||||
- **`crossplane-words.txt`**: Crossplane-specific terms only (CronOperation, XRD, etc.)
|
||||
- **`allowed-jargon.txt`**: General technical terms (kubectl, ConfigMap, etc.)
|
||||
- **`spelling-exceptions.txt`**: Hyphenated terms (day-two, self-signed, etc.)
|
||||
- Keep all dictionaries sorted alphabetically
|
||||
|
||||
### Testing Vale
|
||||
|
||||
**ALWAYS run Vale before considering documentation complete:**
|
||||
|
||||
```bash
|
||||
# Check only warnings and errors (ignore suggestions)
|
||||
vale --minAlertLevel=warning content/
|
||||
|
||||
# Get structured output for analysis
|
||||
vale --output=JSON content/ | jq '.[][] | select(.Severity == "warning")'
|
||||
```
|
||||
|
||||
**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.**
|
||||
|
||||
## Session Management
|
||||
|
||||
- **Pre-Compaction Analysis**: Before compacting chat history, provide a
|
||||
structured session summary including:
|
||||
- Documentation updates made and their impact
|
||||
- Important learnings about Hugo, documentation patterns, or writing guidelines
|
||||
- Potential updates to CLAUDE.md based on new documentation features or workflows
|
||||
- Any recurring style or technical issues encountered
|
||||
Loading…
Reference in New Issue