hexdocs-prod / blogPost / shipping-the-new-docs-pipeline

unsaved changes — 2 fields

Edit entry

model blogPost · version 14 · id e7c1…9b2f

TITLE

SLUG

/blog/

BODY — MARKDOWN

# Shipping the new docs pipeline

Our docs site now builds from structured content instead of hand-maintained markdown files. This post covers the migration path, the schema decisions we got wrong the first time, and the query patterns that survived contact with production.

## What changed

- Content models replace frontmatter — validation happens at write time
- Preview builds trigger on `entry.draft_saved` instead of a cron
- The delivery API now serves code samples as typed blocks, not strings

## Migration in three commands

```
hexdocs models export --workspace docs-old > schema.json
hexdocs models import schema.json --workspace hexdocs-prod
hexdocs entries migrate --from markdown --model docPage
```

The full runbook lives in the engineering handbook; the short version is that 1,900 pages moved in 40 minutes with zero broken links.

LOCALE

AUTHOR

STATUS

Version history

restore creates a new draft — never overwrites

v14current draft — body rewrite, tags addedmara.kessler · 18 min ago
v13published — slug renamed from docs-pipeline-v2mara.kessler · yesterday 16:42
v12autosave — code block language tags fixedsystem · yesterday 15:07
v11imported from markdown — frontmatter mapped to fieldst.okafor · 3 days ago