CMS Migration

Blog Migration From Markdown Files to a Database

Move a file-based blog into Supabase with a source-switch that supports database-only, hybrid-fallback, and filesystem-only modes — so the cutover is reversible and never drops a post.

Start a Project All Case Studies

hmx__websites__

HMX Zone

Source abstraction (lib/blog-source.ts)

1 to 2 weeks

build time

outcomes

stack tools

build steps

Supabase (blog_posts table)

Verified HMX-owned case

Outcome signals

These are the real outcome statements attached to this HMX case study.

Reversible: files stay as a rollback source
No drops: fallback covers any unmigrated post
Sanitized: post HTML cleaned before storage
Editable: posts change without a code deploy

Case architecture

Blog Migration From Markdown Files Architecture

6 nodes

a content-source layer

the posts table and

Supabase

Source abstraction

Fallback Path

Reversible files stay as a

01a content-source layer
Move a file-based blog into Supabase with a source-switch that supports database-only, hybrid-fallback, and filesystem-only modes — so the cutover...
02the posts table and
Create the posts table and migration with sanitized HTML and metadata columns
03Supabase
Supabase (blog_posts table) supports the route, form, or data boundary for Blog Migration From Markdown Files so public UX and backend state stay connected.
04Source abstraction
Write an idempotent, dry-runnable script to import every markdown file
05Fallback Path
When automation confidence is low, route the record to a manual owner with the source, stage, and last action attached.
06Reversible files stay as a
Reversible files stay as a rollback source; No drops fallback covers any unmigrated post; Sanitized post HTML cleaned before storage; Editable post...

Problem

The operating gap

A markdown-file blog cannot be edited without a deploy, has no admin workflow, and risks losing posts in a risky one-shot migration. Going straight to a database with no fallback means any migration bug takes the whole blog offline.

Build

What gets built

Introduce a content-source abstraction with three modes and migrate posts into a Supabase table with sanitized HTML bodies. Run the migration as an idempotent, dry-runnable script, keep the markdown files as a rollback source via hybrid-fallback, and flip to database-only once verification passes — so the cutover is safe and reversible.

Build steps

Blog Migration From Markdown Files to a Database uses a web app route, data, and conversion layer for Full-Stack Websites. Move a file-based blog into Supabase with a source-switch that supports database-only, hybrid-fallback, and filesystem-only modes — so the cutover... The architecture connects a content-source layer, supabase, source abstraction, and reversible files stay as a with an explicit control path.

01Define a content-source layer supporting db-only, hybrid-fallback, and filesystem-only
02Create the posts table and migration with sanitized HTML and metadata columns
03Write an idempotent, dry-runnable script to import every markdown file
04Sanitize rendered HTML on the way in to block unsafe markup
05Run in hybrid-fallback so files cover any post missing from the database
06Verify parity, then switch production to database-only with files as rollback

Stack

Tools and layers

Supabase (blog_posts table)
Source abstraction (lib/blog-source.ts)
gray-matter + remark
sanitize-html
Idempotent migration script
SQL migration

Experience layer: Define a content-source layer supporting db-only, hybrid-fallback, and filesystem-only
Server layer: Create the posts table and migration with sanitized HTML and metadata columns
Database layer: Supabase (blog_posts table) supports the route, form, or data boundary for Blog Migration From Markdown Files so public UX and backend state stay connected.
Automation layer: Source abstraction (lib/blog-source.ts) handles routine steps while introduce a content-source abstraction with three modes and migrate posts into a Supabase table with sanitized HTML bodies.
Measurement layer: Reversible files stay as a rollback source; No drops fallback covers any unmigrated post; Sanitized post HTML cleaned before storage; Editable post...

Data flow

01Define a content-source layer supporting db-only, hybrid-fallback, and filesystem-only
02Create the posts table and migration with sanitized HTML and metadata columns
03Write an idempotent, dry-runnable script to import every markdown file
04Sanitize rendered HTML on the way in to block unsafe markup
05Run in hybrid-fallback so files cover any post missing from the database
06Verify parity, then switch production to database-only with files as rollback

Controls

A markdown-file blog cannot be edited without a deploy, has no admin workflow, and risks losing posts in a risky one-shot migration.
Introduce a content-source abstraction with three modes and migrate posts into a Supabase table with sanitized HTML bodies.
When automation confidence is low, route the record to a manual owner with the source, stage, and last action attached.

Research basis

A route assembles through form, data, metadata, and deploy checks.

The same website operating path

Full-stack websites for service businesses and operators: route architecture, service pages, lead capture, metadata, proof boundaries, blog/database paths, analytics, and deployment checks.

Route map

Service architecture

Clear service routes

01active

Progress72%

Lead capture

Form and context flow

Lead capture that saves context

02active

Progress86%

Public metadata

SEO and schema layer

SEO and schema on public pages

03active

Progress64%

Launch QA

Analytics and deployment checks

Analytics events tied to CTAs

04active

Progress91%