From 6aeda9d47f240a1b9e61e8acffb2309538ab3a19 Mon Sep 17 00:00:00 2001 From: Andy Ford Date: Mon, 2 Feb 2026 10:26:10 +0000 Subject: [PATCH] Add CLAUDE.md for Claude Code guidance Provides guidance for Claude Code when working in this repository: - Development commands (build, test, lint) - Architecture overview and key data structures - MDX content formatting patterns (Code, If, Aside, Tiles, Table) - Available languages per product - Realtime/REST code block prefixes - Workflows for adding pages and updating SDK versions - Writing style guidelines AGENTS.md symlinks to CLAUDE.md for other AI coding assistants. Co-Authored-By: Claude Opus 4.5 --- AGENTS.md | 1 + CLAUDE.md | 280 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 281 insertions(+) create mode 120000 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000000..681311eb9c --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000000..3bb7221dd0 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,280 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is the Ably documentation site (https://ably.com/docs), a Gatsby-based static site using MDX for content. The site covers multiple Ably products: Pub/Sub, Chat, Spaces, LiveObjects, LiveSync, and AI Transport. + +## Development Commands + +```bash +# Quick start (handles asdf tools, yarn install, env setup) +bin/dev + +# Manual setup +yarn install +yarn develop:env-setup # First time only, creates .env.development +yarn develop # Dev server at localhost:8000 + +# Editor mode with refresh endpoint +yarn edit # Enables GATSBY_REFRESH_ENDPOINT +curl -X POST http://localhost:8000/__refresh # Hot refresh + +# Build and serve +yarn build # Production build with prefix paths +yarn serve # Serve production build + +# Testing +yarn test # Run all tests +yarn test:watch # Watch mode +yarn test:ETL # Data transformation tests only (data/) +yarn test:app # App tests only (src/) +jest path/to/file.test.tsx # Single test file + +# Linting +yarn lint # ESLint check +yarn lint:fix # Auto-fix linting issues +``` + +## Architecture + +### Content Organization + +- **`src/pages/docs/`**: MDX content pages organized by product (chat/, spaces/, livesync/, platform/, api/, etc.) +- **`examples/`**: Runnable code examples with JavaScript and React implementations + +### Key Data Structures + +- **`src/data/nav/`**: Navigation config per product (platform.ts, pubsub.ts, chat.ts, spaces.ts, liveobjects.ts, aitransport.ts, livesync.ts) +- **`src/data/languages/`**: Language metadata and SDK versions in `languageData.ts` and `languageInfo.ts` +- **`src/data/content/homepage.ts`**: Homepage content + +### Build Pipeline + +- **`data/createPages/`**: Gatsby page creation and redirect handling +- **`data/onCreateNode/`**: GraphQL schema customization +- **`data/onPostBuild/`**: Post-build processing (asset compression, markdown transpilation for LLMs, redirect validation) + +### Components + +- **`src/components/Layout/`**: Main layout, sidebars, header, MDX wrapper +- **`src/components/Layout/mdx/`**: MDX-specific components (Admonition, Table, NestedTable, PageHeader) + +## Content Formatting (MDX) + +Note: CONTRIBUTING.md describes legacy textile syntax. All content is now MDX. Refer to existing pages for patterns. + +### Frontmatter + +```yaml +--- +title: "Page title" # Required +meta_description: "SEO description" # Required +meta_keywords: "keyword1, keyword2" # Recommended +intro: "Short intro for page header" # Optional +redirect_from: # Optional + - /docs/old/path +--- +``` + +### Headings + +Use standard markdown headings with HTML anchor tags: +```mdx +## Subscribe to messages +``` + +### Available Languages + +See `src/data/languages/languageData.ts` for supported languages per product. Additional syntax languages for code blocks: `shell`, `html`, `json`, `xml`, `sql` + +### Codeblocks + +Wrap in `` component. Consecutive code blocks become language tabs: +```mdx + +```javascript +const channel = realtime.channels.get('channelName'); +``` + +```python +channel = realtime.channels.get('channelName') +``` + +``` + +For Realtime/REST SDK variants, prefix language with `realtime_` or `rest_`. All blocks must be in a single `` tag to render together: +```mdx + +```realtime_javascript +const channel = realtime.channels.get('channelName'); +``` + +```realtime_python +channel = realtime.channels.get('channelName') +``` + +```rest_javascript +const channel = rest.channels.get('channelName'); +``` + +```rest_python +channel = rest.channels.get('channelName') +``` + +``` + +### Variables in Codeblocks + +- `{{API_KEY}}`: Demo API key or user's key selector +- `{{RANDOM_CHANNEL_NAME}}`: Generated channel name + +### Language-specific Content + +Use `` component for conditional content: +```mdx + +Content shown only for JavaScript and Swift. + + + +React-specific content here. + +``` + +### Admonitions + +```mdx + +``` + +Available `data-type` values: +- `note` - General information +- `important` - Critical information (use sparingly) +- `further-reading` - Links to related content +- `new` - New feature announcement +- `updated` - Updated feature announcement +- `experimental` - Experimental feature warning + +### Tiles + +Use for navigation grids (for example, getting started pages): +```mdx + +{[ + { + title: 'JavaScript', + description: 'Start building with Ably\'s JavaScript SDK', + image: 'icon-tech-javascript', + link: '/docs/getting-started/javascript', + }, + { + title: 'Python', + description: 'Start building with Ably\'s Python SDK', + image: 'icon-tech-python', + link: '/docs/getting-started/python', + }, +]} + +``` + +### Nested Tables (API references) + +```mdx + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| typing | optional | Config for typing |
| + +
+ + + +| Property | Required | Description | Type | +| --- | --- | --- | --- | +| heartbeatThrottleMs | optional | Min time between events | number | + + +``` + +The `hidden` attribute prevents the table from rendering directly on the page, but it remains available for nesting via `` references. This keeps type definitions accessible for nested display without duplicating content. + +### Links + +Internal links should start with `/docs`: +```mdx +[messages](/docs/channels/messages) +[Chat SDK](/docs/chat) +``` + +## Adding New Pages + +When creating a new MDX page in `src/pages/docs/`, you must also add it to the navigation: + +1. Create the MDX file with required frontmatter (title, meta_description) +2. Add the page to the appropriate navigation file in `src/data/nav/`: + - `platform.ts` - Platform, auth, integrations, pricing + - `pubsub.ts` - Pub/Sub, channels, messages, presence + - `chat.ts` - Chat product + - `spaces.ts` - Spaces product + - `liveobjects.ts` - LiveObjects product + - `livesync.ts` - LiveSync product + - `aitransport.ts` - AI Transport product + +Navigation entry structure: +```ts +{ + name: 'Section Name', + pages: [ + { + name: 'Page title in nav', + link: '/docs/product/page-slug', + }, + ], +} +``` + +## Updating SDK Versions + +When an SDK version is bumped, update `src/data/languages/languageData.ts`. This file maps products to their SDK versions per language in the language selector: + +```ts +export default { + platform: { + javascript: '2.16', + python: '3.0', + // ... + }, + chat: { + javascript: '1.1', + react: '1.1', + // ... + }, + // ... +} +``` + +## Writing Style + +See `writing-style-guide.md` for full details. Key points: + +- Use International English (US spelling, no Americanisms) +- Use present tense and active voice +- Use second person ("you" not "we") +- Use imperative form for headings ("Configure the client" not "Configuring the client") +- Avoid em-dashes, Latin abbreviations (use "for example" not "e.g."), and slang +- Avoid bold prefixes in bullet points + +## Testing + +Tests use Jest with React Testing Library. Test files are colocated with source files as `*.test.tsx` or `*.test.ts`. + +## CI/CD + +- CI runs in CircleCI +- Add `review-app` label to PR for review deployment +- Tag `@team-deved` for review