Skip to content

chore: add Claude Code config for docs site #131

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ihsraham wants to merge 1 commit into
base: master
Choose a base branch
from
+115 −0
Open

chore: add Claude Code config for docs site #131

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions .claude/rules/docs.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
---
globs: ["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md"]
Copy link
Copy Markdown

@coderabbitai coderabbitai bot Mar 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add blog/**/*.mdx to rule globs.

Line 2 currently applies blog rules only to Markdown files. If blog posts use MDX, these conventions won’t trigger there.

Suggested diff 
-globs: ["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md"]
+globs: ["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md", "blog/**/*.mdx"]
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
globs: ["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md"]
globs: ["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md", "blog/**/*.mdx"]
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In @.claude/rules/docs.md at line 2, Update the globs array so blog MDX files
are included: modify the globs entry (globs: ["docs/**/*.md", "docs/**/*.mdx",
"blog/**/*.md"]) to also include "blog/**/*.mdx" so the pattern becomes globs:
["docs/**/*.md", "docs/**/*.mdx", "blog/**/*.md", "blog/**/*.mdx"]; change the
globs symbol in .claude/rules/docs.md accordingly.

---

- Use MDX for pages needing interactive components; plain Markdown for simple content.
- Always include frontmatter with at least `title` and `sidebar_position`.
- Use Mermaid code blocks for diagrams (theme plugin is configured).
- Use Docusaurus admonitions (`:::note`, `:::tip`, `:::warning`, `:::danger`) for callouts.
- Links between docs must be relative paths, not absolute URLs.
- Code examples must be complete and runnable — no pseudo-code in tutorials.
- Images go in `static/img/` and are referenced as `/img/filename.png`.
- When adding a new doc page, update the relevant sidebar file (`sidebars.ts` or `sidebarsYellowSdk.ts`).
27 changes: 27 additions & 0 deletions .claude/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
{
"permissions": {
"allow": [
"npm start*",
"npm run build*",
"npm run serve*",
"npm run typecheck*",
"npm run sync:*",
"npm run version:*",
"npx prettier*",
"npx docusaurus*",
"git status*",
"git log*",
"git diff*",
"git branch*",
"gh pr *",
"gh issue *",
"gh run *"
],
"deny": [
"git push --force*",
"git reset --hard*",
"rm -rf *",
"npm publish*"
]
}
}
4 changes: 4 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,3 +21,7 @@ npm-debug.log*
yarn-debug.log*
yarn-error.log*
.vercel

# Claude Code local files
.claude/settings.local.json
.claude/agent-memory/
72 changes: 72 additions & 0 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,72 @@
# Yellow Network Documentation Site

Docusaurus 3.9.2 documentation site for Yellow Network / Nitrolite protocol.

## Quick Reference

| Command | What it does |
|---------|-------------|
| `npm start` | Dev server on :3000 |
| `npm run build` | Production build |
| `npm run serve` | Serve production build locally |
| `npm run typecheck` | TypeScript type check |
| `npm run sync:contracts` | Sync contract docs from nitrolite repo |
| `npm run version:release` | Create a new versioned snapshot |
| `npm run version:remove` | Remove a version |

## Site Configuration

- **Config:** `docusaurus.config.ts` — site metadata, plugins, theme config
- **Sidebars:** `sidebars.ts` (main) + `sidebarsYellowSdk.ts` (SDK section)
- **Tailwind:** `tailwind.config.js`, `postcss.config.js`
- **TypeScript:** `tsconfig.json`
- **URL:** https://docs.yellow.org

## Documentation Structure

| Path | Content |
|------|---------|
| `docs/learn/` | Conceptual explainers (architecture, state channels, clearing) |
| `docs/guides/` | How-to guides (integration, setup) |
| `docs/tutorials/` | Step-by-step walkthroughs |
| `docs/api-reference/` | SDK and contract API reference |
| `docs/protocol/` | Protocol specification |
| `docs/build/` | Builder guides |

## Versioning

- Versioned docs live in `versioned_docs/` and `versioned_sidebars/`
- `versions.json` tracks released versions
- Scripts in `scripts/` manage version lifecycle

## Content Conventions

- Use **MDX** for interactive content, plain **Markdown** for simple pages
- Always include frontmatter: `title`, `sidebar_position` (minimum)
- Diagrams: use Mermaid (theme plugin included)
- Admonitions: `:::note`, `:::tip`, `:::warning`, `:::danger`
- Code blocks must be complete and runnable
- Use relative links between docs (not absolute URLs)
- Images go in `static/img/`

## Search

- Primary: Algolia DocSearch
- Fallback: Lunr (local, `docusaurus-lunr-search`)

## Key Files

| File | Purpose |
|------|---------|
| `docusaurus.config.ts` | Site config, plugins, navbar, footer |
| `sidebars.ts` | Main sidebar structure |
| `sidebarsYellowSdk.ts` | SDK docs sidebar |
| `src/pages/` | Custom pages (landing, whitepaper) |
| `src/css/custom.css` | Global style overrides |
| `scripts/sync-contracts-docs.js` | Syncs Solidity NatSpec to docs |

## Git

- Default branch: `master`
- PR target: `master`
- Commit style: `docs|feat|fix(scope): message`
Loading