MetonaSqlark/CONTRIBUTING.md

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

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

Development

# 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

# 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:

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.