Contributing

Thanks for your interest in contributing to N2O!

Code of Conduct

Be respectful, constructive, and inclusive.

Getting Started

1. Fork the repository.
2. Clone your fork: git clone https://github.com/YOUR_USERNAME/n2o.git
3. Install dependencies: npm install
4. Create a branch: git checkout -b feature/your-feature
5. Make your changes.
6. Run tests: npm test
7. Run lint: npm run lint
8. Commit with conventional format.
9. Push and open a Pull Request.

Development Setup

npm install        # Install dependencies
npm run dev        # Start watch mode (hot reload)
npm test           # Run tests
npm run lint:fix   # Fix lint issues

What to Contribute

Good first issues

• Bug fixes with clear reproduction steps
• Test coverage for existing utilities
• Documentation improvements
• Typo fixes

Larger contributions

For significant changes (new features, architecture changes), please open an issue first to discuss the approach.

Areas we’d love help with

• Cross-platform testing (especially macOS and Linux)
• Performance optimization for large vaults (1000+ pages)
• Additional Notion block type support
• Translations / localization

Code Style

• TypeScript strict mode — no any in core code.
• ESLint + Prettier — run npm run lint:fix and npm run format.
• JSDoc on all public APIs.
• Keep it simple — don’t over-engineer.

Commit Messages

Use conventional commits:

type(scope): description

Types: feat, fix, docs, refactor, test, chore, perf

Scopes: core, notion, obsidian, ui, storage, utils, docs

Examples:

feat(core): add attachment deduplication
fix(notion): handle rate limit 429 responses gracefully
docs: update troubleshooting guide

Architecture

N2O uses an intermediate document format that decouples the Notion and Obsidian adapters:

Notion API  →  NotionParser  →  N2ODocument  →  ObsidianBuilder  →  Markdown
Markdown    →  ObsidianParser →  N2ODocument  →  NotionPusher     →  Notion API

Key rules:

• Notion and Obsidian adapters are fully independent — they only share models.
• Use requestUrl from Obsidian for HTTP (never fetch or axios).
• Use processFrontMatter() for YAML changes.

Pull Request Process

1. Ensure all tests pass (npm test).
2. Ensure no lint errors (npm run lint).
3. Update documentation if needed.
4. Add a clear description of what changed and why.
5. Link any related issues.

License

By contributing, you agree that your contributions will be licensed under the MIT License.