eisland-dev-update-docs

Update Docs

This skill guides documentation updates for the eIsland VuePress docs site located at web/eisland-web-docs/.

Core Rules

These rules come from the project's CLAUDE.md and must be followed strictly:

1. Language: All documentation content must be written in English. No Chinese text allowed.
2. Admonitions: Every documentation file MUST use admonition syntax. Each file should include at least one admonition block (:::tip, :::info, :::note, :::important, :::warning, :::danger, or :::details). Use a variety of admonition types — do not rely on a single type.
3. Sidebar: Do NOT register README.md files in the sidebar. VuePress automatically uses each subdirectory's README.md as the category index page.
4. Frontmatter: Every doc file must have YAML frontmatter with title and icon fields.
5. Test Statistics: When documenting test coverage, use accurate numbers from the latest test run: 125 test files, 2068 tests. Update these numbers when new test results show different counts.

Documentation Structure

src/
├── introduction/                # Project introduction and architecture
│   ├── intro/                   # Project introduction
│   ├── tech-stack/              # Technology stack
│   ├── frontend-arch/           # Frontend architecture
│   └── backend-arch/            # Backend architecture
└── developer/                   # Developer guide
    ├── environment-setup/       # Environment configuration
    ├── guides/                  # Development workflows
    ├── standards/               # Coding and documentation standards
    ├── testing/                 # Testing strategies
    ├── commands/                # npm script reference
    └── git-operations/          # Git workflows

Adding New Documentation

Follow these steps in order:

1. Place the file in the appropriate subdirectory under web/eisland-web-docs/src/
2. Add the file path to src/.vuepress/sidebar.ts under the correct group
3. Add a link to the file in the subdirectory's README.md
4. If creating a new subdirectory, create a README.md index for it
5. For API plugin docs: Register sidebar badge in src/.vuepress/components/SidebarBadges.vue if adding Interface, Enum, or Monitor

API Plugin Documentation

For documentation under src/api-plugins/, follow the guidelines in src/api-plugins/CLAUDE.md:

Icon Convention

Every documentation file MUST use the correct icon in frontmatter:

Code Examples

All function/method documentation MUST include both TypeScript and JavaScript code blocks using ::: code-tabs syntax.

Required Sections (Function/Method)

Every function/method document MUST include these sections in this exact order:

1. Info admonition — Brief description with internal mechanism and return type
2. Signature — TypeScript function signature
3. Parameters — Table with Parameter, Type, Description
4. Usage — When to use, typical workflow, :::note and :::tip
5. Return Value — Table with Type and Description, :::warning
6. Example — ::: code-tabs with TS + JS
7. Notes — Exactly 3 admonitions: :::note, :::tip, :::important
8. Danger Avoidance — :::danger admonition

Sidebar Badge Registration

When adding new Interface, Enum, or Monitor documentation, register the badge in src/.vuepress/components/SidebarBadges.vue:

const BADGE_MAP: Record<string, string> = {
  YourNewInterface: 'interface',
  YourNewEnum: 'enum',
  YourNewMonitor: 'monitor',
}

Function badges are auto-detected from URL patterns (get*, set*, close*, etc.).

File Template

Every new documentation file must follow this template:

---
title: Document Title
icon: icon-name
---

# Document Title

:::info
This document covers [brief description of what this document explains]. For related information, see [Related Document](related-doc.md).
:::

## Section Heading

Content here with tables, code blocks, and admonitions.

:::tip
Helpful tips and best practices.
:::

:::warning
Important notices and cautions.
:::

Style Guide

Tables

Use tables for structured data — commands, configurations, comparisons, file listings:

| Command | Script | Description |
|---------|--------|-------------|
| `npm run build` | `vite build` | Build for production |

Code Blocks

Always specify the language:

```bash
npm run build
```

```typescript
const x: string = "hello";
```

```json
{ "key": "value" }
```

Admonition Types

Use the right admonition for the right context:

Cross-References

Link to other documents using relative paths:

See [Frontend Setup](/developer/environment-setup/frontend-setup.md) for details.

Section Pattern for Command/Plugin Docs

For documents that describe commands or plugins, follow this pattern:

## Feature Name

**Brief description** of what this feature does.

### Build / Usage

| Command | Script | Description |
|---------|--------|-------------|
| `npm run build` | `...` | Build description |

### Test

| Command | Script | Description |
|---------|--------|-------------|
| `npm test` | `vitest run` | Run all tests |

### Source Files

| File | Responsibility |
|------|---------------|
| `src/file.ts` | What this file does |

Workflow

When updating documentation:

1. Read the existing file (if updating) or the target directory's README.md (if creating new)
2. Read web/eisland-web-docs/CLAUDE.md for constraints
3. Read 1-2 existing articles in the same directory for style reference
4. Write or update the content following the style guide above
5. Update sidebar.ts if adding a new file
6. Update the parent README.md if adding a new file
7. Verify all admonition blocks are properly closed
8. Verify no Chinese text is present in the content