Contributing to Marzipan #

Thanks for your interest in making Marzipan sweeter! 🍰 We welcome contributions of all kinds - from bug reports to feature implementations.

Code of Conduct #

We're committed to providing a welcoming and inclusive environment. When contributing:

• ✅ Be respectful and considerate
• ✅ Assume good intent
• ✅ Give constructive feedback
• ✅ Focus on what's best for the community
• ✅ Help others succeed

Prerequisites #

Before you begin, make sure you have:

• Node.js 20 or newer (matches engines in package.json)
• npm 9+ (bundled with Node 20)
• Git for version control
• A modern browser for testing

node --version

Getting Started #

1. Fork and Clone #

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR-USERNAME/marzipan.git
cd marzipan
npm install

2. Create a Branch #

# Create a descriptive branch name
git checkout -b feat/amazing-new-feature
git checkout -b fix/annoying-bug
git checkout -b docs/better-examples

3. Make Your Changes #

Edit files, add features, fix bugs - have fun! 🎨

Development Workflow #

Core Library Scripts #

Run these from the repository root:

# Development
npm run dev          # Watch mode - rebuilds on changes
npm run build        # Production build to dist/
npm run typecheck    # TypeScript validation

# Code Quality
npm run lint         # Check code with ESLint
npm run prettier     # Format code and docs

# Full Check
npm run build && npm run lint && npm run typecheck

Bakeshop Demo #

The demo app lives in bakeshop-demo/:

cd bakeshop-demo
npm install

# Development
npm run dev          # Start dev server (localhost:5173)
npm run build        # Production build
npm run preview      # Preview production build

# Code Quality
npm run lint         # ESLint check
npm run typecheck    # TypeScript check
npm run format       # Format code

Project Structure #

marzipan/
├── src/                   # Core library source
│   ├── index.ts           # Main entry point
│   ├── Marzipan.ts        # Core editor class
│   ├── actions/           # Formatting actions
│   │   ├── index.ts
│   │   ├── toggleBold.ts
│   │   └── ...
│   ├── plugins/           # First-party plugins
│   │   ├── tablePlugin.ts
│   │   ├── mermaidPlugin.ts
│   │   └── ...
│   ├── renderer.ts        # Markdown rendering
│   ├── themes.ts          # Theme definitions
│   └── utils.ts           # Utility functions
├── dist/                  # Built files (git ignored)
├── docs/                  # Documentation
├── bakeshop-demo/         # React demo app
├── docs-site/             # VitePress docs site
└── tests/                 # Tests (if any)

Pull Request Guidelines #

Before Submitting #

• [ ] ✅ Code passes npm run lint
• [ ] ✅ Code passes npm run typecheck
• [ ] ✅ Build succeeds with npm run build
• [ ] ✅ Changes tested in Bakeshop demo
• [ ] ✅ Documentation updated (if needed)
• [ ] ✅ CHANGELOG.md updated (for user-facing changes)

PR Checklist #

1. Keep PRs Focused - One feature or fix per PR
2. Write Clear Descriptions - Explain what, why, and how
3. Add Screenshots - For UI changes
4. Link Issues - Reference related issues with #123
5. Update Tests - Add/update tests when appropriate

PR Title Format #

Use conventional commit prefixes:

feat: add table cell navigation
fix: resolve toolbar z-index issue
docs: improve plugin examples
refactor: simplify renderer logic
chore: update dependencies

PR Template #

## Description
Brief description of changes

## Motivation
Why this change is needed

## Changes
- Added X
- Modified Y
- Fixed Z

## Testing
How you tested these changes

## Screenshots
(if applicable)

## Checklist
- [ ] Lint passes
- [ ] TypeCheck passes
- [ ] Tested in Bakeshop
- [ ] Docs updated
- [ ] CHANGELOG.md updated

Commit Guidelines #

Commit Message Style #

Use clear, descriptive commit messages:

# Good ✅
feat: add mermaid dark mode support
fix: prevent toolbar overflow on mobile
docs: clarify plugin installation steps

# Avoid ❌
update stuff
fixed it
changes

Commit Prefixes #

• feat: - New user-facing functionality
• fix: - Bug fixes
• docs: - Documentation changes only
• style: - Code style changes (formatting, no logic changes)
• refactor: - Code restructuring without behavior changes
• perf: - Performance improvements
• test: - Adding or updating tests
• chore: - Tooling, dependencies, build configuration

Types of Contributions #

🐛 Bug Reports #

Found a bug? Open an issue with:

• Clear title describing the issue
• Steps to reproduce the bug
• Expected behavior vs actual behavior
• Environment details (OS, browser, Node version)
• Minimal code example or screenshot
• Error messages if applicable

💡 Feature Requests #

Have an idea? Start a discussion!

Include:

• Use case - Why is this needed?
• Proposed solution - How should it work?
• Alternatives - Other approaches you've considered
• Examples - Similar features in other tools

📚 Documentation #

Docs can always be better!

• Fix typos or unclear wording
• Add more examples
• Improve code snippets
• Translate to other languages
• Create tutorials or guides

💻 Code Contributions #

Adding Actions #

// src/actions/toggleStrikethrough.ts
import type { ActionFunction } from '../types';

export const toggleStrikethrough: ActionFunction = (textarea) => {
  // Your implementation
  const selection = textarea.value.substring(
    textarea.selectionStart,
    textarea.selectionEnd
  );
  
  // Toggle ~~strikethrough~~
  // ...
};

Creating Plugins #

// src/plugins/myAwesomePlugin.ts
import type { MarzipanPlugin } from '../types';

export function myAwesomePlugin(options = {}): MarzipanPlugin {
  return {
    name: 'my-awesome-plugin',
    init(instance) {
      // Plugin initialization
    },
    destroy() {
      // Cleanup
    }
  };
}

See Plugin Development Guide for details.

🎨 Design Contributions #

• Theme designs
• Icon improvements
• UI/UX suggestions
• Accessibility enhancements

Testing Your Changes #

Manual Testing #

1. Core Library

   bash

   npm run build
   cd bakeshop-demo
   npm run dev
   

2. Test in Browser

   • Try different browsers (Chrome, Firefox, Safari)
   • Test responsive design
   • Check console for errors

3. Test Edge Cases

   • Empty content
   • Very long documents
   • Special characters
   • Different themes

Automated Testing #

(Coming soon!)

Updating Documentation #

When making changes:

1. Update README.md - If adding major features
2. Update docs/ - For detailed documentation
3. Update CHANGELOG.md - For all user-facing changes
4. Update type definitions - Keep TypeScript types current

Documentation Site #

The docs site is in docs-site/:

cd docs-site
npm install
npm run dev  # Start docs dev server

Release Process #

(For maintainers)

1. Update version in package.json
2. Update CHANGELOG.md
3. Commit: chore: release v1.x.x
4. Tag: git tag v1.x.x
5. Push: git push && git push --tags
6. Publish: npm publish

Getting Help #

Stuck? Need guidance?

• 💬 GitHub Discussions - Ask questions
• 🐛 Issues - Report bugs
• 📧 Email - Direct contact

Recognition #

All contributors are recognized in:

• GitHub's Contributors page
• Release notes (for significant contributions)
• README.md acknowledgements section

License #

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

See LICENSE for details.

Thank You! 🎉 #

Your contributions make Marzipan better for everyone. Whether you're fixing a typo or implementing a major feature, we appreciate your time and effort!

Made with ❤️ by Pink Pixel