Octodon Development

This skill helps you work with Octodon, a static Mastodon-compatible API server that compiles markdown posts to JSON and serves them via Cloudflare Workers.

Project Architecture

Octodon uses a two-phase approach:

1. **Build Phase** (`src/build.ts`): Converts markdown files in `posts/` to a single `dist/posts.json` with Mastodon-compatible Status objects

2. **Runtime Phase** (`src/worker.ts`): Cloudflare Worker serves JSON from R2 bucket via Mastodon API endpoints

**Design Philosophy**: Intentionally simple (~200 lines total). No pagination, no database, no complex abstractions. Returns all posts; clients handle display.

Development Workflow

Working with Posts

When adding or modifying posts:

1. Create/edit markdown files in `posts/` directory

2. Use filename format: `YYYY-MM-DD-slug.md`

3. Include frontmatter with at minimum a `date` field:

```markdown

---

date: 2025-01-15T10:30:00.000Z

visibility: public

sensitive: false

spoiler_text: ""

language: en

---

Post content in **markdown**.

```

4. Run `npm run build` to compile to `dist/posts.json`

Build and Deploy Process

Follow this exact sequence:

```bash

1. Build the data

npm run build

2. Upload to R2

npx wrangler r2 object put octodon-data/posts.json --file=dist/posts.json

3. Deploy worker

npm run deploy

```

**Note**: Local dev (`npm run dev`) won't have R2 access. Always test post-deployment.

First-Time Cloudflare Setup

If setting up a new environment:

```bash

npx wrangler login # Authenticate

npx wrangler r2 bucket create octodon-data # Create bucket

npx wrangler whoami # Get account ID for CI

```

Testing Deployed Endpoints

After deployment, verify endpoints work:

```bash

curl https://YOUR-WORKER.workers.dev/api/v1/timelines/public

curl https://YOUR-WORKER.workers.dev/api/v1/instance

curl https://YOUR-WORKER.workers.dev/api/v1/statuses/1234567890000

curl https://YOUR-WORKER.workers.dev/api/v1/accounts/1

```

Issue Tracking

**Important**: This project uses [bd (beads)](https://github.com/steveyegge/beads) for issue tracking instead of markdown TODOs. Use `bd` commands to manage tasks. See `AGENTS.md` for workflow details.

Key Files

Important Constraints

Mastodon API Endpoints

The worker implements these minimal endpoints:

All responses include CORS headers for client compatibility.

GitHub Actions CI/CD

The project auto-deploys on push to `main`. Required secrets:

Pipeline: builds posts.json → uploads to R2 → deploys worker

Example Usage

**Adding a new post:**

1. Create `posts/2025-02-06-my-new-post.md`

2. Add frontmatter and content

3. Run build-upload-deploy sequence

4. Test with curl

**Updating account info:**

1. Edit `account.json`

2. Run `npm run build` (updates account metadata in posts.json)

3. Upload and deploy

**Debugging build issues:**