Development workflow for Octodon - a static Mastodon-compatible API server powered by markdown files and Cloudflare Workers. Handles build, deploy, and post management.
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.
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.
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`
Follow this exact sequence:
```bash
npm run build
npx wrangler r2 object put octodon-data/posts.json --file=dist/posts.json
npm run deploy
```
**Note**: Local dev (`npm run dev`) won't have R2 access. Always test post-deployment.
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
```
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
```
**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.
The worker implements these minimal endpoints:
All responses include CORS headers for client compatibility.
The project auto-deploys on push to `main`. Required secrets:
Pipeline: builds posts.json → uploads to R2 → deploys worker
**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:**
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/octodon-development/raw