# Contributing

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](https://github.com/wevm/curl.md/issues) for good first issues.

## Prerequisites

- [OrbStack](https://orbstack.dev) for local Docker support on macOS
- Node.js and `pnpm` for local tools

## Local Setup

:::steps

### Install and start OrbStack

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

```sh
$ orb start
```

### Copy the environment file

And fill out any missing env vars.

```sh
$ cp .env.example .env
```

### Start the app with Docker Compose

You can also run the `pnpm dev` script.

```sh
$ docker compose up -d
```

### Open curl.md locally

Open [https://curl.local](https://curl.local) or request a page directly:

```sh
$ curl curl.local/example.com
```

:::

## Dev Workflow

The app runs inside Docker during local development.

```sh
$ 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`.

```sh
$ 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.

```sh
$ 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:

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

## Checks

Run these before opening a PR:

```sh
$ pnpm check
$ pnpm check:types
```

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

```sh
$ pnpm check:deps
```

## DB Migrations

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

```sh
$ 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.

```sh
$ 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.