MarkdownIt Plugin Development Standards
This skill provides comprehensive coding standards and best practices for developing MarkdownIt plugins using TypeScript.
Code Structure Requirements
Follow these file organization rules:
Write all code in TypeScriptUse `src/index.ts` as the entry point to export the pluginDefine all options in `src/options.ts`Implement plugin logic in `src/plugin.ts`Testing Standards
Implement thorough testing following these guidelines:
Place all test files in the `__tests__` directoryUse `vitest` as the testing frameworkGroup related tests using `describe` blocksTarget 100% code coverage (exceptions only for genuine edge cases)Example test structure:
```ts
describe('plugin feature', () => {
it('should handle basic case', () => {
// test implementation
});
});
```
Performance Optimization
Apply these performance best practices:
String Operations
**Avoid RegExp** in performance-critical paths. Use position pointers and character-by-character logic instead**Minimize string creation**: Avoid `slice()`, `substring()`, and similar methods that create new strings when possible**Use `charCodeAt()` over `charAt()`** for character access and comparisonFor improved readability, use this format:
```ts
str.charCodeAt(index) === 36 /* $ */
```
Variable Management
Define constants at the top of the file to avoid local creation overheadExtract frequently-used static variables to constants (unless it severely impacts type safety or readability)JSDoc Documentation Standards
Scope
JSDoc comments are **required** for all plugin options.
Formatting Rules
Apply these bilingual documentation standards:
**Language**: Include both English and Chinese for all exported content**@default**: Always include for all properties, even for boolean defaults (`@default false`)**@example**: Required only for exported functions**@description**: Optional; use only when additional explanation is needed**@param**: Required for all parameters; use bilingual format separated by `/`**@returns**: Required for all non-void return values; use bilingual format separated by `/`Template:
````ts
/**
* English description
*
* 中文描述
*
* @description (optional) English detailed explanation
*
* 中文详细说明
*
* @param paramName - English description / 中文描述
*
* @default defaultValue
* @example
* ```ts
* // Example TypeScript code
* ```
*/
````
Documentation Guidelines
Follow these principles for user-facing documentation:
Ensure documentation matches actual code behaviorMaintain consistent structure and content between Chinese and English versionsWrite concisely and clearly; remove unnecessary words and avoid redundancyPrefer shorter, clearer explanations when possibleUse "你" (informal) instead of "您" (formal) in Chinese documentationExample: Complete Plugin Option
```ts
/**
* Enable syntax highlighting
*
* 启用语法高亮
*
* @default true
*/
highlight?: boolean;
/**
* Custom renderer function
*
* 自定义渲染函数
*
* @param code - Source code to render / 要渲染的源代码
* @param lang - Language identifier / 语言标识符
* @returns Rendered HTML string / 渲染后的 HTML 字符串
*
* @default undefined
*/
renderer?: (code: string, lang: string) => string;
```
Implementation Checklist
Before submitting a plugin, verify:
[ ] TypeScript code follows file structure (`index.ts`, `options.ts`, `plugin.ts`)[ ] Tests exist in `__tests__/` with vitest[ ] Performance optimizations applied (no unnecessary RegExp, prefer `charCodeAt`)[ ] All options have bilingual JSDoc with `@default` tags[ ] Documentation is bilingual, concise, and matches code behavior[ ] Code coverage reaches 100% (or justified exceptions documented)