Back to Blog
Next.jsSupabaseGitHub ActionsMarkdownWebhookSSRISRSEO

A Next.js Content System in Practice: Syncing Markdown to Supabase with GitHub Actions and Refreshing SSR + ISR Pages via Webhooks

This article describes an engineering approach for content websites: manage Markdown in Git, validate and sync it to Supabase with GitHub Actions, then trigger Next.js revalidation through a webhook for a maintainable SSR + ISR content update flow.

RaytonX
9 min read

When building a content website, the part that is most easily underestimated is not page rendering. It is the whole path content takes from "written" to "reliably live on the page".

For a simple blog, keeping Markdown in the code repository and deploying them together is enough. But as content grows, or as you need collaboration, backend search, tag filtering, and SEO page updates, relying only on local files starts to raise some questions:

  • Does every content update need a redeployment?
  • Is the Markdown frontmatter reliable?
  • Do lists, search, and tag pages need to read structured data?
  • How does the cache refresh promptly after an old page is updated?
  • How do you keep pages and the database consistent after publishing new content?

In our content systems, we have used a fairly restrained approach:

Manage Markdown source files in Git, validate and sync them through GitHub Actions, and write structured content to Supabase. Next.js pages read content from Supabase and combine SSR with ISR to serve cacheable, refreshable pages.

This approach is not meant to replace a full CMS. It balances writing experience, engineering control, and SEO for small teams, content sites, technical blogs, and lightweight knowledge bases.

Overall Architecture

The flow can be split into four parts:

Markdown repository
  │
  │ git push
  ▼
GitHub Actions
  - Read Markdown
  - Validate frontmatter
  - Transform structured fields
  - Upsert to Supabase
  │
  │ Call webhook
  ▼
Next.js Revalidate API
  - revalidateTag
  - revalidatePath
  │
  ▼
Next.js pages
  - SSR reads the latest content
  - ISR caches stable pages

The core idea is: Git is the source of truth for content, Supabase is the online query and index layer, and Next.js handles rendering and caching.

With this setup, content can still be written in Markdown and managed through code review. After launch, pages do not need a redeployment for every update, and content is no longer just files to render but data that can be queried, linked, and reused.

Why Sync to Supabase

For an ordinary blog, reading content/blog/*.mdx directly or fetching Markdown from the GitHub API on the server are both reasonable options.

These approaches are simple and do not need an extra database sync. For a website with few articles that only renders detail and list pages, using files or the GitHub API directly is often the better fit.

We chose to sync to Supabase not because displaying Markdown needs a database, but because the content goes on to serve more use cases:

  1. Easier list queries
    Tags, categories, publish dates, languages, and status can be queried directly with SQL instead of scanning the file system every time.

  2. Access to PostgreSQL's content capabilities
    Once content is in PostgreSQL, you can use indexes, full-text search, joins, sorting, filtering, and statistics. For example, you can group articles by tag, generate related articles, or link guides and case studies to business objects.

  3. A better knowledge source for LLMs
    If you later build intelligent Q&A, content assistants, or RAG, an LLM should not be reading scattered Markdown files on the fly. A safer approach is to put article bodies, summaries, tags, languages, and publish times into the database first, then search and retrieve with PostgreSQL or pgvector.

  4. Clearer content status
    You can distinguish states such as draft, published, and archived, which keeps unpublished content off live pages.

  5. More controllable runtime dependencies
    Live pages read from Supabase instead of calling the GitHub API each time. This reduces external network dependencies and stops GitHub API authentication, rate limits, and network issues from directly affecting page requests.

So the trade-off is: GitHub handles content creation and version management, while Supabase turns content into a data asset that can be queried, searched, and used by LLMs.

Markdown Content Format

Each article keeps a standard MDX/frontmatter structure:

---
title: A Next.js Content System in Practice
slug: nextjs-content-system
date: 2026-07-16
tags: ['Next.js', 'Supabase', 'ISR']
summary: A content publishing approach based on GitHub Actions and Supabase.
status: published
---

Article body...

We write the structured frontmatter fields to regular Supabase columns and the body to a content_markdown field.

A simplified table structure might look like this:

create table blog_posts (
  id uuid primary key default gen_random_uuid(),
  slug text not null unique,
  title text not null,
  summary text,
  content_markdown text not null,
  tags text[] not null default '{}',
  status text not null default 'draft',
  published_at timestamptz,
  updated_at timestamptz not null default now()
);

There is no need to split everything into fine detail right away. For a technical blog or content site, slug, title, summary, tags, status, and content_markdown already cover most page requirements.

Syncing Content with GitHub Actions

GitHub Actions should do more than transfer files to a database. It works more like a content publishing checkpoint.

We recommend that it does at least three things:

  • Validate that frontmatter is complete
  • Validate that fields such as slug, date, and status are legal
  • Upsert Markdown content to Supabase

A simplified sync script might look like this:

import fs from 'node:fs';
import path from 'node:path';
import matter from 'gray-matter';
import { z } from 'zod';
import { createClient } from '@supabase/supabase-js';

const PostSchema = z.object({
  title: z.string().min(1),
  slug: z.string().regex(/^[a-z0-9-]+$/),
  date: z.string(),
  tags: z.array(z.string()).default([]),
  summary: z.string().default(''),
  status: z.enum(['draft', 'published']).default('draft'),
});

const supabase = createClient(
  process.env.SUPABASE_URL!,
  process.env.SUPABASE_SERVICE_ROLE_KEY!,
);

async function syncPost(filePath: string) {
  const raw = fs.readFileSync(filePath, 'utf-8');
  const { data, content } = matter(raw);
  const post = PostSchema.parse(data);

  const { error } = await supabase.from('blog_posts').upsert(
    {
      slug: post.slug,
      title: post.title,
      summary: post.summary,
      tags: post.tags,
      status: post.status,
      published_at: post.date,
      content_markdown: content,
      updated_at: new Date().toISOString(),
    },
    { onConflict: 'slug' },
  );

  if (error) {
    throw error;
  }
}

In GitHub Actions, you only need to run the sync script after a push:

name: Sync Markdown To Supabase

on:
  push:
    branches: [main]
    paths:
      - 'content/**/*.mdx'

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm sync:content
        env:
          SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
          SUPABASE_SERVICE_ROLE_KEY: ${{ secrets.SUPABASE_SERVICE_ROLE_KEY }}

Note that SUPABASE_SERVICE_ROLE_KEY must only live in GitHub Secrets. It should never appear in the browser or in frontend environment variables.

Triggering Revalidation with a Webhook

After content is written to Supabase, Next.js still needs to be told to refresh its cache. GitHub Actions can call an internal endpoint once the sync succeeds:

- name: Revalidate Next.js Pages
  run: |
    curl -X POST "$REVALIDATE_URL" \
      -H "Authorization: Bearer $REVALIDATE_SECRET" \
      -H "Content-Type: application/json" \
      -d '{"type":"blog"}'
  env:
    REVALIDATE_URL: ${{ secrets.REVALIDATE_URL }}
    REVALIDATE_SECRET: ${{ secrets.REVALIDATE_SECRET }}

On the Next.js side, a route handler receives the call:

import { revalidatePath, revalidateTag } from 'next/cache';
import { NextResponse } from 'next/server';

export async function POST(request: Request) {
  const auth = request.headers.get('authorization');

  if (auth !== `Bearer ${process.env.REVALIDATE_SECRET}`) {
    return NextResponse.json({ message: 'Unauthorized' }, { status: 401 });
  }

  const body = await request.json();

  if (body.type === 'blog') {
    revalidateTag('blog-posts');
    revalidatePath('/blog');

    if (body.slug) {
      revalidatePath(`/blog/${body.slug}`);
    }
  }

  return NextResponse.json({ revalidated: true });
}

The key point is that the webhook does not modify pages directly. It only tells Next.js which caches to invalidate.

How SSR and ISR Work Together

In the App Router, pages can read content from Supabase while controlling caching through next: { tags } or revalidate.

For example, a blog list page:

export const revalidate = 3600;

async function getPosts() {
  const { data } = await supabase
    .from('blog_posts')
    .select('slug,title,summary,tags,published_at')
    .eq('status', 'published')
    .order('published_at', { ascending: false });

  return data ?? [];
}

An article detail page can query the body by slug and render the Markdown on the server:

import { MDXRemote } from 'next-mdx-remote/rsc';

export const revalidate = 3600;

export default async function BlogPostPage({
  params,
}: {
  params: Promise<{ slug: string }>;
}) {
  const { slug } = await params;
  const post = await getPostBySlug(slug);

  return (
    <article className="prose">
      <h1>{post.title}</h1>
      <MDXRemote source={post.content_markdown} />
    </article>
  );
}

This way, pages are neither regenerated on every request nor stuck waiting for the next deployment. Most visits hit the cache, and when content changes, a webhook can actively invalidate the affected pages.

That is what SSR + ISR means here:

  • SSR: pages read Supabase data on the server and render HTML
  • ISR: rendered results can be cached and refreshed on demand when content changes

SEO Benefits

The SEO benefit of this approach does not come from a single trick, but from a more stable way of delivering content:

  • The first response returns complete HTML, instead of the browser requesting the body afterwards
  • Titles, summaries, publish dates, and tags all come from structured fields
  • Sitemaps can be generated directly from published content
  • Old articles can be refreshed soon after an update through revalidation
  • Rendered Markdown keeps semantic headings, paragraphs, lists, and code blocks

Search engines do not need to understand your publishing process, but content websites benefit when the resulting pages are stable, crawlable, and easy to update.

Where This Approach Fits

This approach suits:

  • Company website technical blogs
  • Documentation sites
  • Lightweight knowledge bases
  • SEO content sites
  • Small-team content systems that need a Git review process

But it is not right for every project.

If your content editors are not familiar with Git, you may need a backend editor. If content permissions are complex, you will need a separate permission model. If content involves heavy collaborative editing, version comparison, and approval flows, a mature CMS may be a better fit.

The point of an engineering solution is not to make the system heavier, but to make content production, publishing, and rendering clear enough for the current stage.

Summary

The value of this content system lies in separating responsibilities:

  • Markdown handles writing and version management
  • GitHub Actions handles validation and syncing
  • Supabase handles online queries and structured storage
  • Webhooks handle cache refresh notifications
  • Next.js handles server rendering and ISR caching

It introduces no complex CMS and does not tie content updates to full-site deployments. For small and medium content sites, this is a practical path: it keeps the certainty of a Git workflow while giving live pages database queries and on-demand refreshes.