# Contributing to MetonaEditor

Thanks for your interest in contributing! This document outlines the development workflow and conventions.

## Prerequisites

- Node.js >= 16.0.0
- npm >= 8.0.0

## Setup

```bash
git clone https://git.metona.cn/MetonaTeam/MetonaEditor.git
cd MetonaEditor
npm install
```

## Development

```bash
# Start dev server with hot reload (port 3001)
npm run dev

# Run tests in watch mode
npm run test:watch

# Type check
npm run typecheck

# Lint
npm run lint
npm run lint:fix

# Format
npm run format
```

## Project Structure

```
src/
├── index.ts       # Entry point, global API
├── core.ts        # MarkdownEditor class
├── parser.ts      # Markdown parser (tokenizer + renderer)
├── plugins.ts     # Plugin system & 6 presets
├── themes.ts      # Theme system
├── i18n.ts        # Internationalization
├── styles.ts      # CSS-in-JS injection
├── constants.ts   # Types, defaults, configs
├── utils.ts       # Utility functions
├── animations.ts  # Animation metadata
├── icons.ts       # Toolbar SVG icons
└── locales.ts     # Translation data

tests/
├── parser.test.ts
├── core.test.ts
├── plugins.test.ts
├── themes.test.ts
├── i18n.test.ts
├── utils.test.ts
├── animations.test.ts
├── index.test.ts
└── styles.test.ts

site/
├── index.html     # Landing page
├── demo.html      # Full-featured demo
└── docs.html      # API documentation
```

## Code Conventions

### TypeScript
- **Strict mode** is enabled — all code must pass `tsc --noEmit`.
- Export types explicitly. Avoid `any` where possible.
- Use `interface` for object shapes, `type` for unions/primitives.

### Style
- Run `npm run format` before committing (uses Prettier).
- Follow existing comment patterns: JSDoc `/** */` for public APIs, `//` for inline notes.
- Keep functions focused and under ~60 lines where practical.

### Testing
- **Every new feature must include tests.**
- Test files mirror source structure: `src/foo.ts` → `tests/foo.test.ts`.
- Use descriptive test names: `('does X when Y')`.
- Run the full suite before submitting: `npm test`.

### Commits
- Use conventional commit messages:
  - `feat: add reference link resolution`
  - `fix: autoSave plugin state conflict`
  - `docs: update API reference`
  - `test: add index.ts global API tests`
  - `chore: optimize rollup dev build`

## Building

```bash
# Production build (all formats)
npm run build

# Output in dist/
# ├── metona-editor.js        UMD
# ├── metona-editor.min.js    UMD minified
# ├── metona-editor.esm.js    ES Module
# ├── metona-editor.cjs.js    CommonJS
# └── metona-editor.d.ts      TypeScript declarations
```

## Plugin Development

Plugins follow a simple convention:

```typescript
const myPlugin = {
  name: 'myPlugin',
  version: '1.0.0',
  description: 'Description of my plugin',
  depends: [],        // optional: plugin names this depends on
  priority: 50,       // optional: for topological sort ordering

  install(editor, options?) {
    // Called when plugin is installed
    // Use editor.on() to subscribe to events
    // Return a Promise for async initialization
  },

  destroy(editor) {
    // Called when plugin is uninstalled
    // Clean up event listeners, timers, DOM nodes
  },
};
```

## Releasing

1. Update version in `package.json` and `src/index.ts` (`VERSION` constant).
2. Update `CHANGELOG.md`.
3. Run full test suite: `npm test`.
4. Build: `npm run build`.
5. Publish: `npm publish`.

## Questions?

Open an issue at [git.metona.cn/MetonaTeam/MetonaEditor/issues](https://git.metona.cn/MetonaTeam/MetonaEditor/issues).