Skip to content

Commit ef8fa89

Browse files
pwizlapwizla
authored
Add CLAUDE.MD (#3033)
1 parent 13e6d3c commit ef8fa89

1 file changed

Lines changed: 155 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
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 the official Strapi documentation repository, built with Docusaurus 3. The main documentation website is hosted at [docs.strapi.io](https://docs.strapi.io). This repository contains only documentation content - the actual Strapi codebase is in the separate [strapi/strapi](https://github.com/strapi/strapi) repository.
8+
9+
## Development Commands
10+
11+
All development should be done in the `/docusaurus` subdirectory:
12+
13+
```bash
14+
cd docusaurus
15+
```
16+
17+
### Core Commands
18+
19+
- `yarn && yarn dev` - Install dependencies and start development server (port 8080)
20+
- `yarn build` - Build the documentation (required before submitting PRs)
21+
- `yarn serve` - Serve the built documentation locally
22+
- `yarn clear` - Clear Docusaurus cache
23+
24+
### Content Generation
25+
- `yarn generate-llms` - Generate LLM-specific content files
26+
- `yarn llms:generate-and-validate` - Generate and validate LLM code examples
27+
- `yarn validate:llms-code` - Validate existing LLM code examples
28+
29+
### Release and Scripts
30+
- `yarn release-notes` - Generate release notes
31+
- `yarn redirections-analysis` - Analyze URL redirections
32+
33+
### Prerequisites
34+
- Node.js >= 18.15.0 <= 22.x.x
35+
- Yarn >= 1.22.x
36+
- Always run `yarn build` before submitting pull requests to ensure no broken links
37+
38+
## Repository Structure
39+
40+
```
41+
/
42+
├── docusaurus/ # Main Docusaurus application
43+
│ ├── docs/ # Documentation content
44+
│ │ ├── cms/ # Strapi CMS documentation
45+
│ │ └── cloud/ # Strapi Cloud documentation
46+
│ ├── src/ # React components and custom pages
47+
│ ├── static/ # Static assets
48+
│ ├── scripts/ # Build and utility scripts
49+
│ ├── sidebars.js # Sidebar configuration
50+
│ └── docusaurus.config.js # Main configuration
51+
├── agents/ # Documentation review and generation agents
52+
│ ├── prompts/ # AI agent specifications
53+
│ ├── templates/ # Content templates
54+
│ └── authoring/ # Authoring guides
55+
└── .cursor/rules/ # Cursor IDE rules for documentation agents
56+
```
57+
58+
## Documentation Architecture
59+
60+
The documentation is split into two main sections:
61+
- **CMS Docs** (`/docs/cms/`) - Core Strapi CMS features and APIs
62+
- **Cloud Docs** (`/docs/cloud/`) - Strapi Cloud hosting platform
63+
64+
### Content Organization
65+
- Use branch prefix `cms/` for CMS-related changes
66+
- Use branch prefix `cloud/` for Cloud-related changes
67+
- Use branch prefix `repo/` for repository-wide changes
68+
69+
## Writing Guidelines
70+
71+
### Style and Quality
72+
- Follow the [12 Rules of Technical Writing](12-rules-of-technical-writing.md)
73+
- Use the [Style Guide](STYLE_GUIDE.pdf) for formatting conventions
74+
- Disable linters/auto-formatters before saving to prevent rendering issues
75+
76+
### Content Structure
77+
- Use MDX format (Markdown + React components)
78+
- Include proper frontmatter with `title`, `description`, `displayed_sidebar`, `tags`
79+
- Use sentence case for headings
80+
- Include `<Tldr>` components for page summaries
81+
- Use numbered lists for procedures, bullet points for features/options
82+
83+
## Documentation Agent System
84+
85+
This repository includes a comprehensive AI-powered documentation workflow system. **Start with `AGENTS.md`** - it's the main entry point and directory for the entire system.
86+
87+
### System Architecture
88+
89+
- **`AGENTS.md`** - Main directory and entry point, explains the complete system
90+
- **`agents/prompts/`** - Core agent specifications for review and content creation workflows
91+
- **`agents/templates/`** - Content templates for different documentation types
92+
- **`agents/authoring/`** - Area-specific authoring guides (CMS, Cloud, APIs, etc.)
93+
- **`.cursor/rules/`** - Cursor IDE implementations (platform-specific wrappers)
94+
95+
### Available Agents (in `agents/prompts/`)
96+
97+
- **Orchestrator** - Coordinates Review and Create workflows
98+
- **Router** - Identifies document type, determines placement, loads templates
99+
- **Outliner** - Handles all documentation structure tasks with three specialized sub-prompts:
100+
- **Outline Checker** - Ensures template compliance, frontmatter, heading hierarchy
101+
- **Outline UX Analyzer** - Checks reader experience, section order, cognitive load
102+
- **Outline Generator** - Creates outlines from source material (Notion, Jira, specs)
103+
- **Style Checker** - Enforces the 12 Rules of Technical Writing and Strapi conventions
104+
- **Drafter** - Drafts documentation based on inputs from Router and Outliner
105+
- **Integrity Checker** - Coordinates technical verification with two specialized sub-checks:
106+
- **Code Verifier** - Verifies code examples and technical claims against the Strapi codebase
107+
- **Coherence Checker** - Verifies cross-page consistency, links, and terminology
108+
109+
### Workflows
110+
111+
**Review Mode**: `Router → Outliner (Checker) → Style Checker → Integrity Checker`
112+
**Create Mode**: `Router → Outliner (Generator) → Drafter → Style Checker → Integrity Checker`
113+
114+
## Key Configuration Files
115+
116+
- `docusaurus.config.js` - Main Docusaurus configuration
117+
- `sidebars.js` - Navigation structure definition
118+
- `package.json` - Dependencies and build scripts
119+
- `.cursor/rules/` - AI agent specifications for Cursor IDE
120+
- `agents/prompts/` - Standalone AI agent specifications
121+
122+
## Content Validation
123+
124+
### LLMs Integration
125+
The repository includes special handling for LLM (Large Language Model) integrations:
126+
- Auto-generated files: `llms.txt`, `llms-code.txt`
127+
- Validation scripts ensure code examples are accurate
128+
- Content is optimized for AI consumption while maintaining human readability
129+
130+
### Build Process
131+
The build process includes:
132+
1. LLM content generation
133+
2. Code example validation
134+
3. Link checking
135+
4. Static site generation
136+
137+
### Code Examples
138+
- All code examples produced by AI agents MUST be validated against the actual Strapi codebase
139+
- Use the integrity checker to verify technical accuracy
140+
- Include both JavaScript and TypeScript variants when applicable
141+
142+
## Branch and PR Conventions
143+
144+
- Target the `main` branch for most pull requests
145+
- Use descriptive branch names with appropriate prefixes
146+
- Add `flag: merge pending release` label for release-dependent content
147+
- Build locally with `yarn build` before submitting PRs
148+
- Use draft PRs for incremental work
149+
150+
## Important Notes
151+
152+
- **No Strapi codebase in this repo** - Code verification requires access to the separate [strapi/strapi](https://github.com/strapi/strapi) repository
153+
- **Docusaurus-specific** - Uses Docusaurus 3 with custom plugins and components
154+
- **AI-enhanced workflow** - Extensive agent system for content review and generation
155+
- **Multi-product docs** - Covers both CMS and Cloud products with different audiences

0 commit comments

Comments
 (0)