Inkwell

OSS release note: Inkwell is being scrubbed for public release. See docs/OSS-RELEASE-PLAN.md for the current gates, verification commands, and release blockers.

Forkable Astro framework for content + commerce + agent-operated sites. One config file. Cloudflare-native.

Inkwell is a forkable content and commerce framework:

• Markdown/MDX content collections

• Config-driven theming and SEO

• Static search via Pagefind

• Optional Worker-backed reactions, newsletter, and publish APIs

• Inbox-style publishing for agents and automation

• Obsidian-friendly vault mode

Quick Start

npm install
npm run dev

Configure in inkwell.config.ts, then replace demo content under content/en/.

Update workers/inkwell-api/wrangler.toml with the IDs

• Config, not scattered theme code — site identity, theme, analytics, and feature flags live in inkwell.config.ts

• Zero-JS by default — Astro renders HTML; React hydrates only where interactivity matters

• Agent-friendly publishing — content can arrive from inbox files, HTTP APIs, or your own tool layer

• Cloudflare-native optional edge layer — Pages, Workers, KV, D1, and R2 available when needed

Migrate + deploy

npm run migrate:prod npx wrangler deploy

Free. Cloudflare's free tier handles real production workloads.

---

## One Config File

```typescript
// inkwell.config.ts
export const config = {
  name: 'Your Business',
  domain: 'yourbusiness.com',
  tagline: 'Your tagline here.',

  theme: {
    colors: { primary: '#D4A017', secondary: '#06B6D4' },
    fonts: { display: "'Inter', sans-serif" },
    radius: '8px',
  },

  features: {
    reactions: true,
    newsletter: true,
    knowledgeGraph: true,
    search: true,
    chat: false,
  },

  plugins: [
    'auth', 'dashboard', 'content', 'commerce',
    'mcp', 'analytics', 'telegram',
  ],

  adapters: {
    bus: 'standalone',
    memory: 'standalone',
    economy: 'standalone',
  },
}

Toggle a feature off -- its routes and UI disappear. Remove a plugin -- its code never loads. Change an adapter -- infrastructure swaps with zero code changes.

Related MCP server: Substack MCP Server

Connect Your AI

{
  "mcpServers": {
    "my-business": {
      "url": "https://your-worker.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Works with Claude Code, Claude Desktop, ChatGPT, Cursor, Windsurf, or any MCP client.

Project Structure

inkwell.config.ts          # Active site config
inkwell.config.example.ts  # Starter config
content/
  inbox/                   # Drop markdown here for ingest/publish
  en/blog/                 # Blog content
  en/pages/                # Static pages
src/
  pages/                   # Astro routes
  components/
    content/               # Callout, figure, author card, etc.
    engagement/            # Reactions, newsletter, social proof
    layout/                # Header, footer, language switcher
    navigation/            # TOC, command palette, reading progress
    seo/                   # JSON-LD helpers
    visualization/         # Video hero, knowledge graph
workers/
  inkwell-api/             # Optional Cloudflare Worker API
scripts/
  ingest.ts                # Inbox -> content collections
  publish.sh               # Build, commit, push convenience flow
  generate-og.ts           # Open Graph image generator

inkwell.config.ts # All configuration kernel/ # Contracts: types, plugin loader, adapters, RBAC, theme plugins/ # 17 feature modules auth/ # Passwordless OTP auth dashboard/ # Business control panel (React islands) commerce/ # Stripe checkout + subscriptions content/ # MDX publish engine + knowledge graph mcp/ # MCP server (12 tools) organism/ # Managed AI agent provisioning ... workers/inkwell-api/ # Cloudflare Worker (Hono) src/middleware/ # Tenant, auth, RBAC, usage, adapters migrations/ # D1 schema (core, analytics, marketing) wrangler.toml # Bindings + config src/ pages/ # Astro routes (site + dashboard) components/ # Astro + React components layouts/ # Base, Dashboard styles/base.css # Design tokens + Shadcn bridge content/en/ # Markdown content scripts/ # Ingest, publish, fork smoke test instances/ # Per-deployment overrides

---

---

## Commands

| Command | What it does |
|---------|-------------|
| `npm run dev` | Astro dev server |
| `npm run build` | Production build |
| `npm run deploy` | Build + deploy to Cloudflare Pages |
| `npm run ingest` | Process content/inbox/ into collections |
| `npm run publish` | Ingest + build + commit + push |
| `npm run migrate` | Apply D1 migrations (local) |
| `npm run migrate:prod` | Apply D1 migrations (remote) |
| `npm test` | Kernel tests (123 tests) |
| `npm run test:worker` | Worker integration tests (39 tests) |

---

## Publishing Modes

### 1. Inbox publish

Drop a markdown file into `content/inbox/` and run:

```bash
npm run publish

That flow ingests content, builds the site, commits the content changes, and pushes them.

2. Direct content authoring

Write markdown directly into content/en/blog/ or content/en/pages/, then build and commit normally.

3. API-backed publishing

Deploy the Worker layer to expose POST /api/publish — send content from agents or external systems.

Obsidian Vault Mode

The content/en/ tree is set up as an Obsidian vault. Open it directly in Obsidian, or use:

bash scripts/open-obsidian-vault.sh

Built by Inkwell contributors.