Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ragaeeb/paragrafs/llms.txt

Use this file to discover all available pages before exploring further.

​
Welcome Contributors!

Contributions are welcome! We appreciate your interest in improving Paragrafs. Please make sure your contributions adhere to the coding standards and are accompanied by relevant tests.

​
Getting Started

Follow these steps to set up your development environment:
1

Fork the repository

Fork the Paragrafs repository on GitHub to your account.
2

Install Bun

Paragrafs uses Bun as its runtime and package manager. Install it if you haven’t already:
curl -fsSL https://bun.sh/install | bash
3

Clone and install dependencies

Clone your fork and install dependencies:
git clone https://github.com/YOUR_USERNAME/paragrafs.git
cd paragrafs
bun install
4

Make your changes

Create a new branch and make your changes:
git checkout -b feature/your-feature-name

​
Development Workflow

​
Code Quality Checks

Before submitting your changes, ensure they meet our quality standards: 
# Run Biome's formatter and linter
bun run lint
All three commands (lint, build, and test) should pass without errors before submitting a pull request.

​
Project Structure

Paragrafs uses a Bun-native toolchain:

tsdown

Official bundler for compiling TypeScript (configured in tsdown.config.ts)

Biome

Fast linter and formatter (configured in biome.json)

Bun Test

Built-in test runner with coverage support

ESM

Modern ES modules format for all output

​
Coding Standards

​
TypeScript

  • Write type-safe code with proper TypeScript annotations
  • Avoid any types when possible
  • Use interfaces for public APIs
  • Export types alongside implementations

​
Code Style

Biome handles code formatting automatically. Run bun run lint to format your code.
  • Use camelCase for functions and variables
  • Use PascalCase for types and interfaces
  • Use SCREAMING_SNAKE_CASE for constants
  • Use descriptive names that explain intent
  • Add JSDoc comments for public APIs
  • Include examples in complex functions
  • Document parameters and return types
  • Explain any non-obvious behavior

​
Testing Requirements

All new features and bug fixes must include relevant tests.
When writing tests:
  • Cover both happy paths and edge cases
  • Use descriptive test names that explain what’s being tested
  • Aim for high code coverage (check with bun test --coverage)
  • Test public APIs, not implementation details
  • Include tests for Arabic text handling when relevant
Example Test
import { describe, expect, test } from 'bun:test';
import { createHints } from '../src/utils/textUtils';

describe('createHints', () => {
  test('should normalize Arabic text by default', () => {
    const hints = createHints('مرحباً');
    expect(hints).toBeDefined();
    // Add assertions for normalized behavior
  });
});

​
Submitting Changes

1

Run all quality checks

Before submitting, ensure all checks pass:
bun run lint && bun run build && bun test --coverage
2

Commit your changes

Write clear, descriptive commit messages:
git add .
git commit -m "feat: add support for custom hint normalization"
3

Push to your fork

git push origin feature/your-feature-name
4

Submit a pull request

Open a pull request on GitHub with:
  • Clear description of the changes
  • Reference to any related issues
  • Screenshots or examples if applicable
  • Confirmation that tests pass

​
Demo App Development

Paragrafs includes a Svelte + Vite demo app in the demo/ directory:
Demo Commands
# Install demo dependencies
bun run demo:install

# Run development server
bun run demo:dev

# Build demo app
bun run demo:build

# Deploy to Surge
bun run demo:deploy
The demo depends on the local package via file:.., so demo:build automatically runs bun run build first.

​
Contribution Ideas

Looking for ways to contribute? Here are some ideas:

Bug Fixes

Check the issues page for reported bugs

Documentation

Improve examples, add tutorials, or clarify existing docs

Performance

Optimize algorithms for better performance

Features

Propose new features that enhance transcription processing

Tests

Increase test coverage or add edge case testing

Language Support

Enhance support for languages beyond Arabic

​
Code Review Process

After submitting a pull request:
  1. Automated checks will run (CI build, tests, linting)
  2. Maintainer review - a project maintainer will review your code
  3. Feedback - you may receive requests for changes
  4. Approval - once approved, your PR will be merged
  5. Release - your changes will be included in the next release
Be responsive to feedback and questions during code review. It helps get your contribution merged faster!

​
Community Guidelines

  • Be respectful and constructive in discussions
  • Follow the code of conduct (if available)
  • Help other contributors when possible
  • Ask questions if something is unclear

​
License

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

​
Questions?

Open an Issue

Have questions about contributing? Open an issue and we’ll help you get started!

Build docs developers (and LLMs) love

Get started for freeTalk to us