Skip to content

Commit cf19e6e

Browse files
ndbroadbentclaude
ndbroadbent
and
claude
committed
feat: add comprehensive cigen documentation site
- Migrate all content from notes/CACHING.md notes/CIRCLECI.md notes/CONFIG_FORMAT.md notes/JOB_SKIPPING.md notes/NOTES.md notes/OR_DEPENDENCIES.md notes/PHILOSOPHY.md notes/PROJECT_PLAN.md notes/REQUIREMENTS.md notes/TEMPLATING.md files to Astro Starlight documentation - Create 13+ documentation pages covering installation, philosophy, configuration, providers, advanced features, examples, and reference - Fix MDX parsing issues and sidebar configuration - Update syntax throughout to use correct `packages: node` instead of `cache: node_modules` - Remove unnecessary boilerplate (checkout steps) from examples - Add smart cache job deduplication feature documentation - Document CircleCI-specific features including GitHub status fix and OR dependencies - Establish proper navigation structure and organization - Fix linting issues and add prettier ignore for template files - Resolve biome configuration conflicts between root and docs 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
1 parent 2cc685c commit cf19e6e

68 files changed

Lines changed: 21156 additions & 36 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,3 +43,6 @@ flamegraph.svg
4343
/target/doc
4444
/target/criterion
4545

46+
47+
# Renamify workspace
48+
.renamify/

‎.prettierignore‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Exclude YAML template files with intentional formatting issues
2+
src/providers/circleci/templates/patch_approval_jobs_status.yml
3+
4+
# Standard ignores
5+
node_modules/
6+
target/
7+
dist/
8+
build/
9+
.git/

‎CLAUDE.md‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,6 +165,8 @@ This keeps the codebase maintainable and easier to understand.
165165

166166
**CRITICAL**: NEVER implement temporary solutions or workarounds. NEVER say "for now" or "this is not ideal but". Always implement the proper, clean, architectural solution from the start. If something needs to be done right, do it right the first time.
167167

168+
**CRITICAL**: NEVER say "quickly" or "let me quickly" - nothing should be done quickly. Everything requires careful thought and proper implementation. Speed is not a priority; correctness is.
169+
168170
**IMPORTANT**: Work on one small piece at a time. Do not attempt to build the entire project at once.
169171

170172
**CRITICAL: Follow PROJECT_PLAN.md EXACTLY**
@@ -261,9 +263,40 @@ We will start by hand-writing our own GitHub Actions workflow files, but eventua
261263

262264
## DocSpring Configuration Location
263265

264-
**CRITICAL**: When working on DocSpring configuration conversion, the `.cigen/` directory is located in `/Users/ndbroadbent/code/cigen/docspring/.cigen/` (via the symlinked monorepo), NOT in the main cigen repository. This is on the `nathan/cigen-config` branch of the DocSpring monorepo.
266+
**CRITICAL**: The `docspring/` directory in this repository is a SYMLINK to a COMPLETELY SEPARATE repository - the DocSpring monorepo. These are TWO SEPARATE REPOS:
267+
268+
1. **cigen repository** (`/Users/ndbroadbent/code/cigen/`) - The tool itself
269+
2. **DocSpring monorepo** (`/Users/ndbroadbent/code/docspring/`) - A separate private repository
270+
271+
The symlink at `/Users/ndbroadbent/code/cigen/docspring` → `/Users/ndbroadbent/code/docspring` exists ONLY for convenience during development.
272+
273+
**IMPORTANT**:
274+
275+
- The `docspring/` directory is in `.gitignore` - it is IGNORED by git
276+
- It is NOT a submodule
277+
- There is NO git relationship between these repositories
278+
- Changes to files in `docspring/` are tracked by the DocSpring repo, not cigen
279+
- When working on DocSpring configuration, you're editing files in the DocSpring monorepo
280+
281+
When working on DocSpring configuration conversion:
282+
283+
- The `.cigen/` directory is located in the DocSpring monorepo at `/Users/ndbroadbent/code/docspring/.cigen/`
284+
- This is on the `nathan/cigen-config` branch of the DocSpring monorepo
285+
- All job definitions, commands, and templates for DocSpring should be created there
286+
- **You CAN and SHOULD commit DocSpring changes**: Simply `cd docspring` and commit normally
287+
- The whole point is developing cigen AND porting DocSpring CI config in tandem
288+
- DocSpring changes are tracked on its own cigen branch, completely separate from the main cigen repo
289+
290+
## Split Configuration
291+
292+
**IMPORTANT**: CIGen supports a "split config" style where different top-level keys can be refactored into their own files under `.cigen/config/`, and it all gets merged together. This prevents `.cigen/cigen.yml` from becoming unmaintainable.
293+
294+
We MUST use split config for large configuration sections:
265295

266-
The DocSpring configuration uses cigen to replace their existing ERB-based CircleCI configuration system. All job definitions, commands, and templates for DocSpring should be created in `/Users/ndbroadbent/code/cigen/docspring/.cigen/`.
296+
- Source file groups are already split: `docspring/.cigen/config/source_file_groups.yml`
297+
- Any other config section that grows beyond ~20 lines should be split into its own file
298+
- Files in `.cigen/config/` are automatically merged with the main `cigen.yml`
299+
- Use descriptive filenames that match the top-level key (e.g., `cache_definitions.yml` for cache definitions)
267300

268301
## Key Concepts
269302

‎biome.jsonc‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,20 @@
11
{
22
"$schema": "https://biomejs.dev/schemas/2.0.6/schema.json",
3-
"extends": ["ultracite"]
3+
"extends": ["ultracite"],
4+
"linter": {
5+
"rules": {
6+
"style": {
7+
"noParameterAssign": "error",
8+
"useAsConstAssertion": "error",
9+
"useDefaultParameterLast": "error",
10+
"useEnumInitializers": "error",
11+
"useSelfClosingElements": "error",
12+
"useSingleVarDeclarator": "error",
13+
"noUnusedTemplateLiteral": "error",
14+
"useNumberNamespace": "error",
15+
"noInferrableTypes": "error",
16+
"noUselessElse": "error"
17+
}
18+
}
19+
}
420
}

‎docs/.gitignore‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# build output
2+
dist/
3+
# generated types
4+
.astro/
5+
6+
# dependencies
7+
node_modules/
8+
9+
# logs
10+
npm-debug.log*
11+
yarn-debug.log*
12+
yarn-error.log*
13+
pnpm-debug.log*
14+
15+
16+
# environment variables
17+
.env
18+
.env.production
19+
20+
# macOS-specific files
21+
.DS_Store

‎docs/.prettierignore‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
dist/
2+
.astro/
3+
node_modules/
4+
public/
5+
.vercel/
6+
*.json
7+
*.js
8+
*.ts
9+
*.tsx
10+
*.jsx

‎docs/.prettierrc.json‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"singleQuote": true,
3+
"plugins": ["prettier-plugin-astro"],
4+
"overrides": [
5+
{
6+
"files": "*.astro",
7+
"options": {
8+
"parser": "astro"
9+
}
10+
}
11+
]
12+
}

‎docs/.vscode/extensions.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"recommendations": ["astro-build.astro-vscode"],
3+
"unwantedRecommendations": []
4+
}

‎docs/.vscode/launch.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"version": "0.1.0",
3+
"configurations": [
4+
{
5+
"command": "./node_modules/.bin/astro dev",
6+
"name": "Development server",
7+
"request": "launch",
8+
"type": "node-terminal"
9+
}
10+
]
11+
}

‎docs/CLAUDE.md‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# Cigen Documentation - Astro Starlight Guidelines
2+
3+
## Critical Rules
4+
5+
### Never Use H1 Headers in Content
6+
7+
**NEVER** start MDX pages with an H1 (`# Header`) - Starlight automatically
8+
generates the H1 from the frontmatter `title`.
9+
10+
❌ **Wrong:**
11+
12+
```mdx
13+
---
14+
title: MCP Server Configuration
15+
---
16+
17+
# MCP Server Configuration
18+
19+
Content here...
20+
```
21+
22+
✅ **Correct:**
23+
24+
```mdx
25+
---
26+
title: MCP Server Configuration
27+
---
28+
29+
Content here starts immediately, or with H2 (## Section)
30+
```
31+
32+
### Component Imports
33+
34+
Always import Starlight components at the top:
35+
36+
```mdx
37+
import {
38+
Card,
39+
CardGrid,
40+
LinkCard,
41+
Tabs,
42+
TabItem,
43+
Steps,
44+
Code,
45+
Aside,
46+
} from '@astrojs/starlight/components';
47+
48+
;
49+
```
50+
51+
### Best Practices
52+
53+
1. **Structure**: Start content immediately after frontmatter, use H2 for main
54+
sections
55+
2. **Components**: Use `<Steps>` for numbered procedures, `<Tabs>` for
56+
platform-specific content
57+
3. **Cards**: Don't overuse CardGrid - simple lists are often better for
58+
readability
59+
4. **Code blocks**: Use proper language tags for syntax highlighting
60+
5. **Links**: Use LinkCard for prominent external links, regular markdown links
61+
for inline references
62+
63+
### Common Components
64+
65+
- `<Steps>` - Numbered step-by-step instructions
66+
- `<Tabs>` and `<TabItem>` - Platform or option-specific content
67+
- `<LinkCard>` - Prominent navigation to other pages
68+
- `<Aside type="note|tip|caution|danger">` - Callout boxes
69+
- `<Code>` - Inline code with syntax highlighting
70+
71+
### File Structure
72+
73+
- Use kebab-case for file names: `mcp-server-config.mdx`
74+
- Organize in logical directories: `mcp/`, `commands/`, `examples/`
75+
- Use `overview.mdx` for main landing pages in sections
76+
77+
### Frontmatter Requirements
78+
79+
Always include both title and description:
80+
81+
```yaml
82+
---
83+
title: Clear, Descriptive Title
84+
description: Brief description for SEO and navigation
85+
---
86+
```
87+
88+
### Code Examples
89+
90+
When showing cigen CLI output or configuration:
91+
92+
- Use YAML syntax highlighting for config files
93+
- Use bash syntax highlighting for CLI commands
94+
- Show both input config and generated output when relevant
95+
- Use `--config path/to/config` flag in examples
96+
97+
### Testing Guidelines
98+
99+
- Always test configuration examples with `cigen validate`
100+
- Verify generated CI configs with provider CLI tools (e.g., `circleci config validate`)
101+
- Test all links and ensure they work in the local dev server
102+
- Use realistic but simple examples that demonstrate key concepts
103+
104+
### Sidebar Configuration
105+
106+
- Keep sidebar items concise and well-organized
107+
- Use autogenerate for large directories:
108+
`autogenerate: { directory: "commands" }`
109+
- Group related items under clear labels
110+
- Put most important sections (like MCP Server) near the top

0 commit comments

Comments
 (0)