Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
1 change: 1 addition & 0 deletions AGENTS.md
211 changes: 211 additions & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,211 @@
# CLAUDE.md - AI Agent Guidelines for Aptos Documentation

This document provides essential guidelines for AI agents working on the Aptos Developer Documentation repository.

## Project Overview

This repository contains the official Aptos Developer Documentation, built using [Astro](https://astro.build/) and [Starlight](https://starlight.astro.build/). The documentation is available in multiple languages including English, Spanish (es), and Chinese (zh).

## Development Setup

### Prerequisites

- **Node.js:** Version 22.x (use [nvm](https://github.com/nvm-sh/nvm))
- **pnpm:** Version 10.2.0 or higher (`npm install -g pnpm`)

### Quick Start

```bash
pnpm install # Install dependencies
cp .env.example .env # Set up environment variables
pnpm dev # Start development server (http://localhost:4321)
```

## Essential Commands

| Command | Description |
| --------------------- | ----------------------------- |
| `pnpm dev` | Start the development server |
| `pnpm build` | Build the site for production |
| `pnpm lint` | Check for linting issues |
| `pnpm format` | Fix formatting issues |
| `pnpm check` | Run Astro type checking |
| `pnpm format:content` | Format MDX content files |

## Project Structure

```
src/
├── content/
│ ├── docs/ # Main English documentation
│ │ ├── es/ # Spanish translations
│ │ └── zh/ # Chinese translations
│ ├── i18n/ # UI translations
│ └── nav/ # Sidebar translations
├── components/ # Reusable components
├── config/ # Configuration helpers
└── assets/ # Site assets
```

## Critical Guidelines

### 1. Linting and Formatting

**IMPORTANT:** All changes must pass linting and formatting checks before completion.

```bash
pnpm lint # Run all linters (eslint + prettier)
pnpm format # Fix formatting issues
```

Run these commands after making changes to ensure code quality.

### 2. Translation Requirements

**All documentation changes must be translated and verified in both Chinese and Spanish versions.**

- **English docs:** `src/content/docs/`
- **Spanish docs:** `src/content/docs/es/`
- **Chinese docs:** `src/content/docs/zh/`

When modifying documentation:

1. Make the change in the English version first
2. Create or update the corresponding Spanish translation in `es/`
3. Create or update the corresponding Chinese translation in `zh/`
4. Ensure all internal links use the correct language prefix (e.g., `/es/network/` for Spanish)

### 3. Commit Message Requirements

Every commit should have a clear, descriptive message that explains the changes made.

Format:

```
<type>: <description>

<optional body with more details>
```

Types:

- `docs`: Documentation changes
- `feat`: New features
- `fix`: Bug fixes
- `style`: Formatting changes
- `chore`: Maintenance tasks

Example:

```
docs: add glossary entry for BlockSTM

Added definition and example for BlockSTM parallel execution engine.
Updated Spanish and Chinese translations accordingly.
```

### 4. Grammar and Style

**Grammar check every change** before committing. Ensure:

- Clear, concise language
- Consistent terminology throughout the documentation
- Proper sentence structure and punctuation
- Technical accuracy in all explanations
- Active voice preferred over passive voice

### 5. Glossary Requirements

**Ensure new terms are defined in the Glossary.**

The glossary is located at:

- **English:** `src/content/docs/network/glossary.mdx`
- **Spanish:** `src/content/docs/es/network/glossary.mdx`
- **Chinese:** `src/content/docs/zh/network/glossary.mdx`

When adding a new term to the glossary:

1. **Define the term clearly** - Provide a concise, accurate definition
2. **Provide an example** - Include practical examples or use cases
3. **Add context** - Link to related documentation where appropriate
4. **Consider diagrams** - Add diagrams for complex concepts when helpful

Glossary entry format:

```markdown
### Term Name

- **Term Name** is [definition].
- [Additional context or explanation].

See [Related Page](/path/to/page) for more information.
```

### 6. MDX File Structure

Documentation files use MDX format with frontmatter:

```yaml
---
title: "Page Title"
description: "Brief description of the page content"
sidebar:
label: "Sidebar Label" # Optional
---
```

### 7. Internal Links

Use relative paths without the file extension:

- English: `/network/blockchain/accounts`
- Spanish: `/es/network/blockchain/accounts`
- Chinese: `/zh/network/blockchain/accounts`

## Content Guidelines

### Writing Style

- Use clear, simple language accessible to developers of all skill levels
- Define technical terms on first use or link to the glossary
- Include code examples where appropriate
- Structure content with clear headings and subheadings

### Code Blocks

Use fenced code blocks with language identifiers:

```move
module example::hello {
public fun greet(): vector<u8> {
b"Hello, Aptos!"
}
}
```

## Common Tasks

### Adding a New Documentation Page

1. Create the MDX file in the appropriate directory
2. Add frontmatter with title and description
3. Create Spanish translation in `es/` subdirectory
4. Create Chinese translation in `zh/` subdirectory
5. Update sidebar configuration if needed (`astro.sidebar.ts`)
6. Run `pnpm lint` and `pnpm format`

### Updating the Glossary

1. Add the term to `src/content/docs/network/glossary.mdx`
2. Add Spanish translation to `src/content/docs/es/network/glossary.mdx`
3. Add Chinese translation to `src/content/docs/zh/network/glossary.mdx`
4. Ensure alphabetical ordering within each section
5. Include definition, examples, and links to related content

## Resources

- [Astro Documentation](https://docs.astro.build/)
- [Starlight Documentation](https://starlight.astro.build/)
- [MDX Documentation](https://mdxjs.com/)
- [Aptos Developer Portal](https://aptos.dev)
5 changes: 5 additions & 0 deletions astro.sidebar.ts
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,11 @@ export const sidebar = [
"build/sdks/wallet-adapter/x-chain-accounts",
],
}),
{
label: "Forklift",
link: "build/sdks/forklift",
badge: { text: "NEW", variant: "tip" },
},
// Community SDKs
group("build.group.sdks.community-sdks", {
collapsed: true,
Expand Down
50 changes: 27 additions & 23 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -34,16 +34,16 @@
"packageManager": "pnpm@10.2.0",
"dependencies": {
"@aptos-labs/ai-chatbot-client": "^0.1.4",
"@astrojs/node": "^9.5.1",
"@astrojs/node": "^9.5.2",
"@astrojs/partytown": "^2.1.4",
"@astrojs/react": "^4.4.2",
"@astrojs/sitemap": "^3.6.0",
"@astrojs/starlight": "^0.37.1",
"@astrojs/sitemap": "^3.7.0",
"@astrojs/starlight": "^0.37.3",
"@astrojs/starlight-docsearch": "^0.6.1",
"@astrojs/starlight-tailwind": "^4.0.2",
"@astrojs/tailwind": "^6.0.2",
"@astrojs/vercel": "^9.0.2",
"@iconify/json": "^2.2.425",
"@astrojs/vercel": "^9.0.4",
"@iconify/json": "^2.2.430",
"@nanostores/react": "^1.0.0",
"@octokit/graphql": "^9.0.3",
"@radix-ui/react-dialog": "^1.1.15",
Expand All @@ -52,10 +52,10 @@
"@vercel/edge": "^1.2.2",
"@vercel/og": "^0.8.6",
"@vercel/speed-insights": "^1.3.1",
"astro": "^5.16.6",
"astro-mermaid": "^1.2.0",
"astro": "^5.16.11",
"astro-mermaid": "^1.3.1",
"class-variance-authority": "^0.7.1",
"firebase": "^12.7.0",
"firebase": "^12.8.0",
"jose": "^6.1.3",
"lucide-react": "^0.562.0",
"mermaid": "^11.12.2",
Expand All @@ -72,28 +72,28 @@
"devDependencies": {
"@astrojs/check": "^0.9.6",
"@astrojs/markdown-remark": "^6.3.10",
"@crowdin/cli": "^4.12.0",
"@crowdin/cli": "^4.13.0",
"@eslint/js": "^9.39.2",
"@expressive-code/plugin-collapsible-sections": "^0.41.5",
"@expressive-code/plugin-collapsible-sections": "^0.41.6",
"@graphiql/toolkit": "^0.11.3",
"@iconify-json/ph": "^1.2.2",
"@readme/openapi-parser": "^5.4.0",
"@scalar/api-client": "^2.17.1",
"@scalar/snippetz": "^0.6.1",
"@swc/core": "^1.15.8",
"@readme/openapi-parser": "^5.5.0",
"@scalar/api-client": "^2.18.4",
"@scalar/snippetz": "^0.6.5",
"@swc/core": "^1.15.10",
"@tailwindcss/vite": "^4.1.18",
"@types/gtag.js": "^0.0.20",
"@types/node": "^25.0.3",
"@types/react": "^19.2.7",
"@types/node": "^25.0.9",
"@types/react": "^19.2.9",
"@types/react-dom": "^19.2.3",
"@types/react-syntax-highlighter": "^15.5.13",
"@vercel/node": "^5.5.16",
"@vercel/node": "^5.5.25",
"astro-embed": "^0.10.0",
"astro-eslint-parser": "^1.2.2",
"astro-favicons": "^3.1.5",
"astro-icon": "^1.1.5",
"astro-seo-schema": "^5.1.0",
"baseline-browser-mapping": "^2.9.11",
"baseline-browser-mapping": "^2.9.16",
"eslint": "^9.39.2",
"eslint-config-flat-gitignore": "^2.1.0",
"eslint-config-prettier": "^10.1.8",
Expand All @@ -111,7 +111,7 @@
"mdast-util-to-string": "^4.0.0",
"nano-staged": "^0.9.0",
"openapi-types": "^12.1.3",
"prettier": "^3.7.4",
"prettier": "^3.8.0",
"prettier-plugin-astro": "^0.14.1",
"rehype-katex": "^7.0.1",
"rehype-raw": "^7.0.0",
Expand All @@ -123,17 +123,17 @@
"satori-html": "^0.3.2",
"schema-dts": "^1.1.5",
"sharp": "^0.34.5",
"shiki": "^3.20.0",
"shiki": "^3.21.0",
"simple-git-hooks": "^2.13.1",
"starlight-llms-txt": "^0.7.0",
"starlight-openapi": "^0.21.1",
"starlight-package-managers": "^0.11.1",
"tsx": "^4.21.0",
"typescript": "^5.9.3",
"typescript-eslint": "^8.52.0",
"typescript-eslint": "^8.53.1",
"unist-util-remove": "^4.0.0",
"unist-util-visit": "^5.0.0",
"vite": "^7.3.0",
"vite": "^7.3.1",
"vite-plugin-monaco-editor": "^1.1.0"
},
"pnpm": {
Expand All @@ -144,6 +144,7 @@
"vite-plugin-monaco-editor@1.1.0": "patches/vite-plugin-monaco-editor@1.1.0.patch"
},
"overrides": {
"diff": ">=8.0.3",
"@anthropic-ai/claude-code": ">=2.0.31",
"vite": "^7.3.0",
"esbuild": ">=0.25.0",
Expand All @@ -156,7 +157,10 @@
"tar": ">=7.5.2",
"js-yaml": ">=4.1.1",
"mdast-util-to-hast": ">=13.2.1",
"sharp": ">=0.34.0"
"sharp": ">=0.34.0",
"preact": ">=10.28.2",
"lodash": ">=4.17.23",
"lodash-es": ">=4.17.23"
}
},
"simple-git-hooks": {
Expand Down
Loading
Loading