Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
343 lines (252 loc) · 6.84 KB

CONTRIBUTING.md

File metadata and controls

343 lines (252 loc) · 6.84 KB

Contributing to @create-markdown

Thank you for your interest in contributing to @create-markdown! This document provides guidelines and instructions for contributing.

Code of Conduct

Please read and follow our Code of Conduct.

Monorepo Structure

This project is a monorepo managed with Turborepo and pnpm.

create-markdown/
├── packages/
│   ├── core/           # @create-markdown/core - Zero-dep parsing/serialization
│   ├── mdx/            # @create-markdown/mdx - Markdown to MDX conversion
│   ├── react/          # @create-markdown/react - React components and hooks
│   ├── preview/        # @create-markdown/preview - HTML rendering with plugins
│   ├── docs/           # @create-markdown/docs - Documentation site
│   └── create-markdown/ # Convenience bundle re-exporting all packages
├── playground/         # Demo application
└── .changeset/         # Changesets for version management

Prerequisites

Getting Started

  1. Fork and clone the repository

    git clone https://github.com/YOUR_USERNAME/create-markdown.git
cd create-markdown

  2. Install dependencies

    pnpm install

  3. Build all packages

    pnpm run build

  4. Run tests

    pnpm run test

  5. Run the playground

    pnpm run playground

Development Workflow

Working on a Package

Each package can be developed independently:

# Build a specific package
cd packages/core
pnpm run build

# Watch mode
pnpm run dev

# Run package tests
pnpm run test

Available Scripts

Script Description
pnpm run build Build all packages
pnpm run test Run all tests
pnpm run typecheck Type check all packages
pnpm run lint Lint all packages
pnpm run clean Clean all build artifacts
pnpm run playground Run the demo playground

Adding a Changeset

When making changes that should be released, add a changeset:

pnpm changeset

This will prompt you to:

  1. Select which packages have changed
  2. Choose the semver bump type (major, minor, patch)
  3. Write a summary of the changes

When to add a changeset:

  • Bug fixes (patch)
  • New features (minor)
  • Breaking changes (major)
  • Documentation changes affecting usage (patch)

When NOT to add a changeset:

  • Internal refactoring without API changes
  • Test additions
  • CI/CD changes
  • README updates (unless affecting usage)

Branch Naming

Use descriptive branch names with prefixes:

  • feature/ - New features
  • fix/ - Bug fixes
  • docs/ - Documentation
  • refactor/ - Code refactoring
  • test/ - Test additions/changes

Examples:

  • feature/katex-plugin
  • fix/inline-code-parsing
  • docs/react-hooks-guide

Commit Messages

Follow Conventional Commits:

type(scope): description

[optional body]

[optional footer]

Types:

  • feat - New feature
  • fix - Bug fix
  • docs - Documentation
  • style - Formatting (no code change)
  • refactor - Code refactoring
  • test - Adding tests
  • chore - Maintenance tasks

Scopes:

  • core - @create-markdown/core
  • react - @create-markdown/react
  • preview - @create-markdown/preview
  • playground - Demo app
  • ci - CI/CD
  • deps - Dependencies

Examples:

feat(preview): add KaTeX plugin for math rendering
fix(core): handle empty code blocks correctly
docs(react): add useBlockEditor examples

Pull Request Process

  1. Create a feature branch

    git checkout -b feature/my-feature

  2. Make your changes

    • Write clear, documented code
    • Add tests for new functionality
    • Update documentation as needed

  3. Run checks locally

    pnpm run build
pnpm run typecheck
pnpm run test

  4. Add a changeset (if applicable)

    pnpm changeset

  5. Push and create a PR

    git push origin feature/my-feature

  6. Fill out the PR template

    • Describe your changes
    • Link related issues
    • Check the checklist

Code Style

TypeScript

  • Use explicit types for function parameters and returns
  • Prefer interfaces over type aliases for object shapes
  • Use JSDoc comments for public APIs
  • Follow existing patterns in the codebase
/**
 * Parses markdown string into blocks
 * 
 * @param markdown - The markdown string to parse
 * @param options - Optional parsing options
 * @returns Array of parsed blocks
 * 
 * @example
 * ```ts
 * const blocks = parse('# Hello\n\nWorld');
 * ```
 */
export function parse(
  markdown: string,
  options?: MarkdownParseOptions
): Block[] {
  // ...
}

Formatting

  • 2-space indentation
  • Single quotes for strings
  • No semicolons
  • Max line length: 100 characters

File Organization

// 1. Imports (external, then internal)
import React from 'react';
import type { Block } from '@create-markdown/core';

// 2. Types and interfaces
export interface MyProps {
  // ...
}

// 3. Constants
const DEFAULT_OPTIONS = {
  // ...
};

// 4. Helper functions (private)
function helperFunction() {
  // ...
}

// 5. Main exports
export function mainFunction() {
  // ...
}

Testing

We use Vitest for testing.

Running Tests

# Run all tests
pnpm run test

# Run tests for a specific package
cd packages/core
pnpm run test

# Watch mode
pnpm run test:watch

# With coverage
pnpm run test -- --coverage

Writing Tests

import { describe, it, expect } from 'vitest';
import { parse, stringify } from '../src';

describe('parse', () => {
  it('should parse headings', () => {
    const blocks = parse('# Hello');
    expect(blocks[0].type).toBe('heading');
    expect(blocks[0].props.level).toBe(1);
  });
});

Test Coverage

Aim for 80%+ coverage. Focus on:

  • Core parsing/serialization logic
  • Edge cases and error handling
  • Public API contracts

Package-Specific Guidelines

@create-markdown/core

  • Zero dependencies (except devDependencies)
  • All functions should be pure when possible
  • Comprehensive JSDoc comments

@create-markdown/react

  • Peer dependency on React 18+
  • Server component compatible when possible
  • Hooks follow React conventions

@create-markdown/preview

  • Plugins are optional peer dependencies
  • Web Component follows custom elements spec
  • CSS themes are self-contained

Questions?

License

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