Markdown Writing Guidelines

Follow these guidelines when writing component README.md to ensure proper document rendering and navigation.

Heading Rules

Do NOT Start Headings with Numbers

Headings must not start with a digit, otherwise the sidebar table of contents will fail to scroll to the target section.

<!-- ❌ Wrong: heading starts with a number -->
## 1. Install Dependencies
## 2. Basic Usage
## 2024 Changelog

<!-- ✅ Correct: text comes first -->
## Step 1: Install Dependencies
## Step 2: Basic Usage
## Changelog (2024)

Why: The platform uses CSS selectors to locate headings for scroll anchoring. CSS selectors cannot start with a digit — #1.-Install-Dependencies is an invalid selector. Clicking a TOC item will highlight the menu but the page won't scroll.

Heading Hierarchy

• H1 (#): Document title — only one per document
• H2 (##): Main sections — 3 to 8 recommended
• H3 (###): Subsections — as needed
• H4 (####): Details — use sparingly

# Component Name

## Installation

## Basic Usage

### Props

### Events

## Examples

### Basic Example

### Advanced Example

Other Considerations

Avoid Special Characters

Do not use special characters (<>{}[]|, etc.) in headings, as they may interfere with anchor generation:

<!-- ❌ Avoid -->
## Props {#custom-id}

## <MyComponent> Usage

<!-- ✅ Recommended -->
## Props

## MyComponent Usage

No Pure Numeric Headings

<!-- ❌ Avoid -->
## 2023
## 2024

<!-- ✅ Recommended -->
## 2023 Updates
## 2024 Updates

No HTML Tags in Headings

<!-- ❌ Avoid -->
## <code>hello()</code> Method

<!-- ✅ Recommended -->
## hello() Method

<!-- Or use backticks -->
## `hello()` Method

Content Guidelines

Document Structure

A well-structured component README should include:

1. Introduction (## Introduction): One-line description of the component
2. Installation (## Installation): Dependencies and import instructions
3. Basic Usage (## Basic Usage): Minimal working example
4. API Reference: Props, Events, Slots (tables preferred)
5. Examples: Typical use cases

Code Blocks

Always specify the language for proper syntax highlighting:

```vue
<template>
  <Button>Click</Button>
</template>
```

```js
import { ref } from 'vue'
```

Tables

Use tables for Props / Events documentation:

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Button size |
| `disabled` | `boolean` | `false` | Whether disabled |

Links

• Internal anchors: [Installation](#installation)
• External links: [Vue Docs](https://vuejs.org)

Quick Checklist

Before publishing a component, verify your README:

• [ ] Headings do not start with digits or special characters
• [ ] Heading hierarchy is reasonable (H2 for main, H3 for sub)
• [ ] Code blocks have a language specified
• [ ] Includes a basic usage example
• [ ] Props / Events are clearly documented