#ContributingCopy page

Thank you for your interest in contributing to curl.md! We’re building the best way to go from URL to markdown, and we’d love your help.

Use this page to get a local curl.md development environment running and learn how to contribute.

#Ways To Contribute

We welcome and appreciate any form of contributions, here are some ideas:

• Bug Reports Report markdown extraction issues, share performance regressions, or document edge cases
• Feature Development Add new agent plugins or site profiles, rules, and extraction methods.
• Documentation Add new guides or improve areas that were difficult to understand.
• Testing Improve test coverage, create performance benchmarks, or level up plugin tests.
• Infrastructure Improve build and CI systems, or maintain compat with other tools.

You can also check out GitHub issues for good first issues.

#Prerequisites

• OrbStack for local Docker support on macOS
• Node.js and pnpm for local tools

#Local Setup

1. 1

   Install and start OrbStack

   OrbStack provides the local Docker runtime used by curl.md on macOS.

   $orb start

2. 2

   Copy the environment file

   And fill out any missing env vars.

   $cp .env.example .env

3. 3

   Start the app with Docker Compose

   You can also run the pnpm dev script.

   $docker compose up -d

4. 4

   Open curl.md locally

   Open https://curl.local or request a page directly:

   $curl curl.local/example.com

#Dev Workflow

The app runs inside Docker during local development.

$docker compose up$docker logs curl -f

#Local Package Scripts

Use these scripts to exercise the shipped CLI and plugin entrypoints against your local app at https://curl.local.

$pnpm md example.com$pnpm plugin amp

• pnpm md runs the local CLI against https://curl.local
• pnpm plugin [name] runs agent plugin locally. You can also run short versions: pnpm amp, pnpm opencode, pnpm pi, etc.

#Testing

Use scoped Vitest projects while iterating, then run the broader set that matches your change.

$pnpm test --project cli$pnpm test --project plugins:pi$pnpm test --project app --project md --project workers

When working on browser behavior, run browser or E2E coverage as needed:

$pnpm test --project browser$pnpm test:e2e

#Checks

Run these before opening a PR:

$pnpm check$pnpm check:types

If you changed dependencies in cli/ or plugins/, also run:

$pnpm check:deps

#DB Migrations

When you change the schema, create a migration, apply it locally, then regenerate database types.

$pnpm db:make your_migration_name$pnpm db:migrate latest$pnpm db:codegen

Use a descriptive snake_case migration name.

#Changesets

If your change affects a published package or release notes, add a changeset.

$pnpm changeset

That creates a markdown file in .changeset/ where you select the package and bump type.

Docs-only or purely local dev changes usually do not need a changeset.

#Docs

Docs live in docs/ and are rendered through the src/docs/ route in app.

If you add or update docs, make sure the sidebar in docs/_sidebar.ts stays in sync.