MarkdownIt Plugins Coding Standards

You are assisting with development of MarkdownIt plugins in the mdit-plugins project. All code must follow these strict standards.

Project Structure

1. **Entry point**: `src/index.ts` - exports the plugin

2. **Options definition**: `src/options.ts` - all plugin options

3. **Plugin logic**: `src/plugin.ts` - core implementation

4. **Tests**: `__tests__/` directory with vitest

Code Standards

Language & Structure

Write all code in TypeScript

Follow the three-file structure above for all plugins

Export plugin from `src/index.ts`, define options in `src/options.ts`, implement in `src/plugin.ts`

Performance Rules (CRITICAL)

**String Operations:**

AVOID RegExp in performance-critical paths - use position pointers instead

AVOID `slice`, `substring`, or methods that create new strings

PREFER `charCodeAt` over `charAt` for character access

Use format: `str.charCodeAt(index) === number /* char */` for readability

- Example: `str.charCodeAt(index) === 36 /* $ */`

**Variables:**

Define constants at file top to avoid local creation overhead

Extract static variables used multiple times to constants (unless it breaks types/readability)

Testing Standards

Place all tests in `__tests__/` directory

Use vitest framework

Group tests with `describe` blocks by testing case

Target 100% code coverage (except genuine edge cases)

JSDoc Requirements

Required Scope

All plugin options MUST have JSDoc

Format Rules

**Structure:**

```typescript

/**

* English description

* 中文描述

* @description (optional, only if clarification needed) English detailed description

* 中文详细描述

* @param paramName - English description / 中文描述

* @default defaultValue

* @example

* ```ts

* // Example code

* ```

```

**Required Fields:**

Bilingual (English + Chinese) for all exported content

`@default` - ALWAYS include for all properties (even `@default false`)

`@param` - Required for all parameters, bilingual with `/` separator

`@returns` - Required for non-void returns, bilingual with `/` separator

`@example` - Only for exported functions

**Optional:**

`@description` - Use only when additional explanation is needed

Documentation Standards

1. **Consistency**: Docs must match code behavior exactly

2. **Bilingual parity**: Chinese and English must have matching structure and content

3. **Conciseness**: Remove unnecessary words, avoid redundancy, prefer shorter

4. **Chinese style**: Use "你" instead of "您"

When Writing Code

1. Start with the three-file structure

2. Apply performance rules - avoid RegExp and string methods, use charCodeAt

3. Write comprehensive tests with vitest in `__tests__/`

4. Add complete bilingual JSDoc with required fields

5. Ensure documentation matches implementation

Example Character Code Check

```typescript

// GOOD - Performance optimized

const HASH = 35; // #

if (str.charCodeAt(pos) === HASH /* # */) {

// process

}

// BAD - Avoid these

if (/^#/.test(str)) { } // RegExp

if (str.charAt(pos) === '#') { } // charAt

const sub = str.slice(pos); // string creation

```

MarkdownIt Plugins Standards