Content Publish

Publish content to joelclaw.com through the Convex-first pipeline. Every article, tutorial, note, and essay flows through this skill.

Content Types

Type	fields.type	When to use
article	article	Standard blog post, opinion, narrative
tutorial	tutorial	Implementable spec — agent or human can build from it
note	note	Short observation, link commentary, video note
essay	essay	Long-form, thesis-driven

Tags must include the content type. A tutorial gets tags: [..., "tutorial"]. An essay gets tags: [..., "essay"]. This enables filtered views and search facets.

Lifecycle

1. Draft

Upsert to Convex with draft: true:

npx convex run contentResources:upsert '<JSON>'

Required fields:

{
  "resourceId": "article:<slug>",
  "type": "article",
  "fields": {
    "title": "The Title",
    "slug": "the-slug",
    "description": "One-liner for cards and meta",
    "date": "2026-03-02T10:14:00.000Z",
    "tags": ["topic1", "topic2", "tutorial"],
    "draft": true,
    "content": "Full MDX body (frontmatter stripped)"
  }
}

Slug rules: lowercase, hyphenated, no special chars. Derived from title. Check for collisions first:

npx convex run contentResources:getByResourceId '{"resourceId": "article:<slug>"}'

Date: Full ISO datetime, not bare date. Determines sort order.

Content: Strip any frontmatter from MDX before setting fields.content. The frontmatter fields are stored as separate Convex fields, not inline.

2. Content preparation

For large content, prepare the JSON payload with Node to handle escaping:

cd ~/Code/joelhooks/joelclaw/apps/web

node -e "
const fs = require('fs');
const content = fs.readFileSync('<path-to-mdx>', 'utf-8')
  .replace(/^---[\\\\s\\\\S]*?---\\\\n/, '').trim();
const args = {
  resourceId: 'article:<slug>',
  type: 'article',
  fields: {
    title: '<title>',
    slug: '<slug>',
    description: '<description>',
    date: '<ISO datetime>',
    tags: [<tags>],
    draft: true,
    content: content,
  },
};
fs.writeFileSync('/tmp/convex-args.json', JSON.stringify(args));
"

npx convex run contentResources:upsert \"\$(cat /tmp/convex-args.json)\"

Always run npx convex from apps/web/ — that's where the Convex config and generated API types live.

3. Review

Drafts are visible in dev only (NODE_ENV === "development"). Preview at localhost:3000/<slug>.

Drafts return 404 in production — this is correct. Do not publish without review confirmation from Joel unless the content was explicitly pre-approved.

4. Publish

Update the document with draft: false and set updated timestamp:

# Re-run the upsert with draft: false
# Add fields.updated = current ISO datetime

5. Revalidate

Lease the revalidation secret and hit the API:

# Lease secret (TTL auto-managed)
SECRET=$(joelclaw secrets lease revalidation_secret)

curl -s -X POST "https://joelclaw.com/api/revalidate" \
  -H "Content-Type: application/json" \
  -d "{
    \"secret\": \"$SECRET\",
    \"tags\": [\"post:<slug>\", \"article:<slug>\", \"articles\"],
    \"paths\": [\"/\", \"/<slug>\", \"/<slug>.md\", \"/<slug>/md\", \"/feed.xml\", \"/sitemap.md\"]
  }"

Expected response: {"revalidated": true, ...}

Tag convention:

• post:<slug> — individual post cache
• article:<slug> — content resource cache
• articles — list page cache
• Always include all three tags + the markdown/feed/sitemap paths

6. Verify

# Must return 200
curl -s -o /dev/null -w "%{http_code}" "https://joelclaw.com/<slug>"

# Markdown twin must return 200 and current content
curl -s -o /dev/null -w "%{http_code}" "https://joelclaw.com/<slug>.md"

# Must appear on homepage
curl -s "https://joelclaw.com" | grep -c "<slug>"

# Feed should include it
curl -s "https://joelclaw.com/feed.xml" | grep -c "<slug>"

All four checks must pass. If the slug page returns 404 after revalidation, the Convex document is likely still draft: true or content is missing.

Updating existing content

Same upsert flow. Set fields.updated to bump sort position. Always revalidate after update.

Gotchas

• Convex CLI must run from apps/web/ — it needs the project config
• Content must have frontmatter stripped — Convex fields ARE the metadata; don't duplicate in content body
• ISO datetimes, not bare dates — 2026-03-02T10:14:00.000Z not 2026-03-02
• Secret is ephemeral — lease from agent-secrets, never hardcode or cache
• Large content needs JSON escaping — use Node script to build payload, not manual string interpolation
• Tags must include content type — tutorials get "tutorial" tag, essays get "essay" tag
• The filesystem content/ directory is gitignored seed material — Convex is the source of truth at runtime