Skip to main content
Thank you for considering contributing to CodeInk! This guide will help you understand our development process and how to submit contributions.

​
Code of Conduct

CodeInk is an open-source project licensed under the MIT License. We welcome contributions from everyone who wants to improve the project.

MIT License

CodeInk is free and open-source software. You’re free to use, modify, and distribute it under the terms of the MIT License.Copyright (c) 2026 Jorge Florentino

​
Ways to Contribute

Report Bugs

Found a bug? Open an issue on GitHub with steps to reproduce

Suggest Features

Have an idea? Create a feature request issue

Fix Issues

Browse open issues and submit pull requests

Improve Docs

Help improve documentation and guides

​
Getting Started

1

Fork the repository

Fork jorgefl8/codeink to your GitHub account.
2

Clone your fork

git clone https://github.com/YOUR_USERNAME/codeink.git
cd codeink
3

Install dependencies

bun install
4

Create a branch

Create a descriptive branch name:
git checkout -b fix/editor-scroll-bug
# or
git checkout -b feature/export-html
5

Make your changes

Follow our coding standards and test your changes locally:
bun dev
6

Run type checking

Ensure no TypeScript errors:
bun run lint

​
Coding Standards

​
TypeScript Guidelines

Always use explicit types for function parameters and return values:
// ✅ Good
export function saveDoc(doc: Document): Promise<void> {
  return withStore("readwrite", (store) => store.put(doc))
}

// ❌ Bad
export function saveDoc(doc) {
  return withStore("readwrite", (store) => store.put(doc))
}
Prefer async/await over promise chains:
// ✅ Good
async function loadDocument(id: string) {
  const doc = await getDoc(id)
  if (!doc) return null
  return doc.content
}

// ❌ Bad
function loadDocument(id: string) {
  return getDoc(id).then(doc => {
    if (!doc) return null
    return doc.content
  })
}
  • Functions: camelCase (createEditor, renderPreview)
  • Components: PascalCase (Editor.astro, StatusBar.astro)
  • Constants: UPPER_SNAKE_CASE (DB_NAME, AUTO_SAVE_DEBOUNCE_MS)
  • Interfaces: PascalCase (Document, EditorOptions)

​
File Organization

// src/components/Example.astro
---
import type { Props } from './types'

interface Props {
  title: string
  description?: string
}

const { title, description } = Astro.props
---

<div class="component">
  <h2>{title}</h2>
  {description && <p>{description}</p>}
</div>

<style>
  /* Scoped styles */
</style>

<script>
  // Client-side scripts
</script>

​
CSS/Styling Guidelines

Use Tailwind utility classes for styling:
<!-- ✅ Good -->
<button class="px-4 py-2 rounded-md bg-primary text-primary-foreground hover:bg-primary/90">
  Click me
</button>

<!-- ❌ Avoid custom CSS when Tailwind suffices -->
<button class="custom-button">
  Click me
</button>
Use CSS custom properties defined in src/styles/tokens.css:
.custom-component {
  background: var(--background);
  color: var(--foreground);
  border: 1px solid var(--border);
}
Available tokens:
  • Colors: --background, --foreground, --primary, --muted-foreground
  • Spacing: Use Tailwind classes
  • Typography: --font-sans, --font-mono

​
Testing Your Changes

​
Manual Testing Checklist

Before submitting, test the following:
1

Editor functionality

  • Editor loads and displays content
  • Typing updates the preview
  • Syntax highlighting works
  • Theme switching works
2

Markdown rendering

  • Headings, lists, and formatting render correctly
  • Code blocks have syntax highlighting
  • Mermaid diagrams render
  • Math expressions (KaTeX) render
3

Document management

  • Documents save automatically
  • Documents load from URL hash
  • Document list displays correctly
  • Delete functionality works
4

Cross-browser compatibility

Test in multiple browsers:
  • Chrome/Edge
  • Firefox
  • Safari
5

Responsive design

Test at different screen sizes:
  • Desktop (1920x1080)
  • Tablet (768x1024)
  • Mobile (375x667)

​
Build Testing

Test the production build: 
bun run build
bun run preview
Ensure:
  • No build errors
  • No TypeScript errors
  • All features work in production mode

​
Submitting Pull Requests

1

Commit your changes

Write clear, descriptive commit messages:
git add .
git commit -m "fix: resolve editor scroll issue on mobile"
Commit message format:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation changes
  • style: Code style changes (formatting)
  • refactor: Code refactoring
  • perf: Performance improvements
  • test: Adding tests
  • chore: Maintenance tasks
2

Push to your fork

git push origin fix/editor-scroll-bug
3

Open a pull request

  1. Go to the CodeInk repository
  2. Click “Pull Requests” → “New Pull Request”
  3. Select your fork and branch
  4. Fill out the PR template
4

PR description template

Include the following in your PR description:
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation update

## Testing
- [ ] Tested locally
- [ ] Ran type checking
- [ ] Tested in multiple browsers
- [ ] Tested responsive design

## Screenshots (if applicable)
[Add screenshots here]

## Related Issues
Fixes #123

​
Pull Request Review Process

  1. Automated checks: TypeScript type checking runs automatically
  2. Maintainer review: A maintainer will review your code
  3. Feedback: Address any requested changes
  4. Approval: Once approved, your PR will be merged
PRs typically receive initial feedback within 3-5 days.

​
Areas That Need Help

Looking for where to contribute? Here are priority areas:

Export Formats

Add HTML, PDF, or DOCX export functionality

Collaborative Editing

Implement real-time collaboration features

Mobile Experience

Improve mobile editor UX and gestures

Accessibility

Enhance keyboard navigation and screen reader support

Internationalization

Add multi-language UI support

Plugin System

Design extensible plugin architecture

​
Development Tips

Access the CodeMirror instance in browser console:
// Get editor content
document.querySelector('.cm-editor').cmView.state.doc.toString()

// Get lint diagnostics
import { diagnosticCount } from '@codemirror/lint'
diagnosticCount(view.state)
View stored documents in browser DevTools:
  1. Open DevTools → Application tab
  2. Expand “IndexedDB” → “codeink-docs”
  3. Click “documents” store
HMR is enabled by default. For script changes that don’t reload:
// Add to your script file
if (import.meta.hot) {
  import.meta.hot.accept()
}
Use browser DevTools Performance tab:
  1. Start recording
  2. Type in editor
  3. Stop recording
  4. Look for long tasks (>50ms)
Focus areas: markdown parsing, syntax highlighting, preview rendering

​
Getting Help

GitHub Discussions

Ask questions and discuss ideas

GitHub Issues

Report bugs and request features

​
Recognition

Contributors are recognized in:
  • GitHub contributors list
  • Release notes for significant contributions
  • Project README
First-time contributors: Look for issues labeled good first issue to get started!

​
Next Steps

Setup Guide

Set up your development environment

Architecture

Understand the codebase architecture

Code Structure

Learn the project organization

Build docs developers (and LLMs) love

Get started for freeTalk to us