eisland-dev-update-docs

name

eisland-dev-update-docs

description

Update or create documentation in the eIsland VuePress docs site (web/eisland-web-docs). Use this skill whenever the user asks to update docs, add documentation, write a doc article, document a feature, update the tech stack docs, update plugin docs, update command docs, or any task involving files under web/eisland-web-docs/src/. This skill ensures all documentation follows the project's CLAUDE.md constraints, uses correct admonition syntax, maintains consistent style with existing articles, and properly updates sidebar.ts and README.md indexes.

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:

Type	Icon	Example
Function/Method	fa6-solid:code	getIconByPath
Interface/Type	fa6-solid:table	BluetoothDeviceInfo
Class/Monitor	fa6-solid:cubes	BluetoothMonitor
Enum	fa6-solid:list	BatteryStatus
Plugin index	Category icon	bluetooth, music, etc.

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:

Type	Use For
:::info	Document introduction, general explanations
:::tip	Best practices, helpful shortcuts
:::note	Supplementary information, side notes
:::important	Key information users must be aware of
:::warning	Cautions, potential issues, breaking changes
:::danger	Critical security notes, destructive operations
:::details	Collapsible sections, long code references

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