MarkdownIt Plugins Development

Develop and maintain MarkdownIt plugins following the mdit-plugins project standards. This skill enforces TypeScript best practices, performance optimization patterns, bilingual documentation, and comprehensive testing coverage.

Instructions

Code Structure

1. **File Organization**

- Use `src/index.ts` as the entry file to export the plugin

- Use `src/options.ts` for options definition

- Use `src/plugin.ts` for plugin implementation

- Write all code in TypeScript

2. **Performance Optimization**

- **Avoid RegExp**: Do not use regular expressions, especially in performance-critical paths. Use position pointers to access characters with logic instead

- **Avoid String Creation**: Minimize use of `slice`, `substring`, and similar methods that create new strings

- **Use charCodeAt**: Prefer `charCodeAt` for character access and comparison instead of `charAt`

- Format: `str.charCodeAt(index) === number /* char */`

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

- **Constants**: Define constants at the top of the file to avoid local creation overhead

- **Extract Static Variables**: If a static variable is used multiple times, extract it to a constant unless it breaks readability or causes type issues

3. **Testing Requirements**

- Place test files in `__tests__` directory

- Use `vitest` for testing

- Group tests by testing cases with `describe`

- Target 100% code coverage unless edge cases are truly exceptional

4. **JSDoc Standards**

**Scope**: Required for all plugin options

**Format**:

- **Bilingual**: Write in both English and Chinese for all exported content

- **@default**: Always include for all properties (including `@default false`)

- **@example**: Only for exported functions

- **@description**: Optional, only if necessary for additional explanation

- **@param**: Required for all parameters, bilingual, separate with `/`

- **@returns**: Required for all return values except `void` and `Promise<void>`, bilingual, separate with `/`

**Template**:

```ts

/**

* English description

*

* 中文描述

*

* @description (optional) English detailed description

*

* 中文详细描述

*

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

*

* @default defaultValue

* @example

* ```ts

* // Example code in TypeScript

* ```

*/

```

5. **Documentation Standards**

- Keep consistent with code behavior

- Maintain identical structure and content between Chinese and English

- Write concisely and clearly, remove unnecessary words, avoid redundancy

- Use "你" instead of "您" in Chinese

Implementation Steps

When creating or modifying a MarkdownIt plugin:

1. **Create File Structure**

- Set up `src/index.ts`, `src/options.ts`, `src/plugin.ts`

- Create `__tests__` directory for test files

2. **Implement Plugin Logic**

- Define options interface in `options.ts` with bilingual JSDoc

- Implement plugin in `plugin.ts` following performance rules

- Export from `index.ts`

3. **Optimize Performance**

- Replace RegExp with character-by-character parsing using `charCodeAt`

- Extract constants to file top

- Minimize string operations

- Use position pointers for string traversal

4. **Write Tests**

- Create test file in `__tests__`

- Group tests with `describe` blocks

- Aim for 100% code coverage

- Use `vitest` as test runner

5. **Document Code**

- Add bilingual JSDoc to all exported options and functions

- Include `@default`, `@param`, `@returns` as required

- Add `@example` for exported functions

- Keep documentation concise and consistent across languages

Constraints