Forem: Raşit

I finally launched the SaaS version of my headless CMS

Raşit — Sat, 18 Apr 2026 11:21:19 +0000

I’ve been working on Noma for quite a while now, and the hosted SaaS version is finally live: app.nomacms.com.

So yeah, it’s no longer just something you self-host. There are real workspaces, billing, proper multi-tenant isolation, and a dashboard you can just open and start using. No setup, no “clone the repo and configure things first”. It feels pretty good to finally reach this point.

From the beginning, I wanted Noma to be API-first. Before worrying about UI, I focused on building a content model that actually holds up in production. Things like collections and fields, singletons vs lists, validation, relations, locales with linked translations, assets, webhooks, and project-scoped API keys with clear permissions. The kind of foundation you don’t have to fight later.

Turning that into a SaaS was a whole different challenge. It’s not just “it works on my server” anymore. I had to deal with tenant database isolation, subscriptions and trials (I’m using Lemon Squeezy), file uploads that scale on S3 with direct and multipart flows, webhook delivery with logs you can actually inspect, and rate limiting in the right places. None of this is exciting to show in screenshots, but without it you don’t really have a product people can rely on.

On the developer side, I wanted the experience to be predictable. Something you can integrate without guesswork. There’s a typed @nomacms/js-sdk, consistent error responses, and patterns that work across Next.js, Nuxt, Astro, mobile backends, or anything else that speaks HTTP. The goal is that you don’t have to reverse engineer how things behave.

AI is also a core part of it, but not in a “let’s add a chatbot” way. A lot of real work now happens inside coding tools and agents, so ignoring that didn’t make sense. Inside the dashboard, there’s a Noma AI Assistant that can interact with your projects, schema, and content. You can also use AI directly in fields to generate content, rewrite, fix grammar, summarize, or translate without leaving the editor. For multilingual setups, there’s entry-level translation with locale linking built in.

Outside the dashboard, I added MCP support so tools like Cursor or Claude Code can operate on your project using standard environment config. There are also agent “skills” so these tools actually understand how Noma works, like auth and SDK usage, instead of guessing and breaking things on the first attempt.

If you want to try it, you can check it out at nomacms.com. There’s a 7-day trial.

And if you’re curious about any part of it, whether it’s tenancy, API design, or how the AI pieces fit together, I’m happy to go into details. I’ve been deep in this codebase for a long time, so fresh feedback is always useful.

Introducing NomaCMS

Raşit — Fri, 17 Apr 2026 09:56:54 +0000

We are excited to introduce NomaCMS, a headless content platform built for teams that want structured content, a clean API, and a real place for AI inside their workflow. This post walks through what NomaCMS is and what you can do with it today.

What NomaCMS is

NomaCMS is a headless CMS. Your content lives in a structured layer, and your applications read and write it through a REST API or our JavaScript SDK. The dashboard at app.nomacms.com is where you model your content, create entries, upload assets, manage locales, and configure webhooks. Your frontend stays completely separate, which means you can ship the same content to a website, a mobile app, an internal tool, or anywhere else that can make an HTTP request.

Structured content modeling

Content in NomaCMS is organized into collections, and each collection has its own fields. A collection can be a list, like blog posts or products, or a singleton, like a homepage or a settings record. Fields cover the types you would expect from a modern CMS, including text, long text, rich text, slug, email, password, number, enumeration, boolean, color, date, time, datetime, media, relation, JSON, and group. That means you can model a simple blog or a more involved product catalog without reaching for workarounds.

Entries support draft and published states, bulk create, update, and delete, and flexible filtering when you list them.

A REST API and a typed JavaScript SDK

Every project gets a REST API secured with API keys. On top of that, the @nomacms/js-sdk package gives you a typed client with grouped methods for projects, collections, fields, content, assets, and webhooks. A minimal setup looks like this:

import { createClient } from "@nomacms/js-sdk"

const noma = createClient({
  projectId: process.env.NOMA_PROJECT_ID,
  apiKey: process.env.NOMA_API_KEY,
})

const posts = await noma.content.list("posts")

The SDK maps API errors to typed exceptions and handles details like the project-id header for you, so you can focus on your application.

Assets, webhooks, and localization

The asset library handles file uploads, including direct and multipart uploads for large files, plus bulk upload and bulk metadata updates. Webhooks let you react to content and auth events, with delivery logs you can inspect when something looks off.

For multilingual projects, you can define locales at the project level, pick a default, and link translated entries together so your frontend can navigate between them cleanly.

Project authentication for your users

NomaCMS also handles end-user authentication for your application. Your users can sign up with email and password or sign in with social providers, refresh their sessions, and manage their own per-user API keys. Everything is scoped to the project, so you do not need to stand up a separate auth service just to let users log in to the app you are building on top of NomaCMS.

Built-in AI, without the lock-in

AI shows up in three clear places.

Inside the dashboard, the Noma AI Assistant can help you create projects, build collections, manage entries, and navigate the product through conversation. In any text or rich text field, inline tools let you generate, rewrite, expand, summarize, fix grammar, or translate content on the spot. And when it is time to translate a whole entry, one click can move it into another locale and link the translations together.

AI coding tools, first class

If you work in Cursor, Claude Code, or Windsurf, our MCP server plugs your editor straight into your project. It exposes tools for project, collection, field, content, asset, and webhook management, so you can say what you want in plain language and have it show up in your CMS.

To go further, the Noma Agent Skills package teaches your coding assistant how to use the SDK, follow our auth patterns, and integrate with Next.js, Nuxt, and Astro, so you spend less time explaining the basics every time you start a task.

Getting started

If you want to try it out, head to app.nomacms.com, create a project, install the SDK, and fetch your first entries. We will be sharing more guides and updates here on the blog as we roll out new features. Thanks for checking out NomaCMS.

I turned my headless CMS into an AI-native CMS. Here’s what happened.

Raşit — Fri, 13 Feb 2026 13:54:12 +0000

I’ve been building ElmapiCMS for a while. It’s a Laravel + React headless CMS for developers.

But something kept bothering me.

AI tools were exploding everywhere, yet most CMS platforms were just adding a simple “Generate text” button and calling it AI integration.

So I decided to go deeper and turn the CMS itself into something AI-native.

Here’s what changed.

1. From text generation to schema-aware AI

Instead of generating random paragraphs, I made the AI aware of:

Collection name
Field labels
Existing field values
Locale

Now when you generate content, the output is influenced by the actual structure of your data model.

That small shift made a big difference in quality and relevance.

2. Conversational schema creation

I added an AI Chat Assistant that can:

Create projects
Create collections
Define fields
Generate entries

You can describe a “blog with title, slug, content and author relation” and it scaffolds it.

This was technically much harder than adding content generation, because it touches schema integrity and validation.

3. One-click translation

Since the structure is already defined, I added full entry translation per locale.

Instead of translating field by field, you translate the whole entry in one action.

For agencies handling multilingual clients, this is powerful.

4. MCP server for AI-driven workflows

This was the most interesting part.

I implemented an MCP server so external AI agents can interact directly with the CMS:

Create collections
Modify schema
Insert content
Query structured data

The idea is to support vibecoding workflows, where AI doesn’t just write frontend code but can shape the backend in a controlled way.

5. The reality check

Technically, this is the strongest version I’ve built.

Commercially? Visibility is still hard.

Adding AI features does not magically solve distribution.

What I learned:

Depth matters more than surface AI features
Schema context dramatically improves output quality
Multi-provider support adds complexity fast
Distribution is harder than development

I’m still figuring out the go-to-market side.

If you’re building in the CMS, AI tooling, or developer infrastructure space, I’d love to hear from you.

How to Create a Next.js Blog - Part 3: Advanced Features

Raşit — Mon, 12 Jan 2026 12:09:20 +0000

Polishing Your Blog with Advanced Features

In Part 1 and Part 2, we built a functional blog with search and categories. Now we'll add professional touches: related posts, social sharing, enhanced code blocks, and comprehensive SEO.

What You'll Build

By the end of Part 3, you'll have:

Related posts that suggest similar content
Social share buttons for X, Facebook, and LinkedIn
Code blocks with copy-to-clipboard functionality
Comprehensive SEO with Open Graph and X Cards
Reading time calculation
Author information display

Prerequisites

Before starting, make sure you've completed Part 1 and Part 2, and have:

Individual post pages working
Table of contents implemented
Search and categories functional

Related posts help readers discover more content. We'll show posts from the same category, with a fallback to other posts.

Implementing getRelatedPosts()

Update lib/posts.ts:

export async function getRelatedPosts(currentSlug: string, limit: number = 3): Promise<PostMatter[]> {
  const allPosts = await getSortedPostsData()
  const currentPost = allPosts.find((post) => post.slug === currentSlug)

  if (!currentPost) {
    return []
  }

  // Get all posts excluding the current one
  const otherPosts = allPosts.filter((post) => post.slug !== currentSlug)

  if (otherPosts.length === 0) {
    return []
  }

  // Separate posts by category match
  const sameCategoryPosts = otherPosts.filter(
    (post) => post.category && post.category === currentPost.category
  )
  const differentCategoryPosts = otherPosts.filter(
    (post) => !post.category || post.category !== currentPost.category
  )

  // Shuffle arrays for randomness
  const shuffle = <T,>(array: T[]): T[] => {
    const shuffled = [...array]
    for (let i = shuffled.length - 1; i > 0; i--) {
      const j = Math.floor(Math.random() * (i + 1));
      [shuffled[i], shuffled[j]] = [shuffled[j], shuffled[i]]
    }
    return shuffled
  }

  const shuffledSameCategory = shuffle(sameCategoryPosts)
  const shuffledDifferentCategory = shuffle(differentCategoryPosts)

  // Mix posts: prefer same category but ensure variety
  const relatedPosts: PostMatter[] = []

  // Take up to 2 posts from same category (if available)
  const sameCategoryCount = Math.min(2, shuffledSameCategory.length, limit)
  relatedPosts.push(...shuffledSameCategory.slice(0, sameCategoryCount))

  // Fill remaining slots with random posts from different categories
  const remaining = limit - relatedPosts.length
  if (remaining > 0 && shuffledDifferentCategory.length > 0) {
    relatedPosts.push(...shuffledDifferentCategory.slice(0, remaining))
  }

  // If we still don't have enough, fill with any remaining posts
  const stillRemaining = limit - relatedPosts.length
  if (stillRemaining > 0) {
    const allRemaining = [
      ...shuffledSameCategory.slice(sameCategoryCount),
      ...shuffledDifferentCategory.slice(remaining)
    ]
    relatedPosts.push(...allRemaining.slice(0, stillRemaining))
  }

  return relatedPosts.slice(0, limit)
}

This function:

Finds posts in the same category first
Falls back to other categories if needed
Randomizes results for variety
Limits the number of related posts

Creating the RelatedPosts Component

Create components/related-posts.tsx:

import Link from 'next/link'
import { PostMatter } from '@/lib/posts'
import { formatDate } from '@/lib/utils'
import { Badge } from '@/components/ui/badge'
import { ArrowRight } from 'lucide-react'

interface RelatedPostsProps {
  posts: PostMatter[]
}

export function RelatedPosts({ posts }: RelatedPostsProps) {
  if (posts.length === 0) {
    return null
  }

  return (
    <section className="mt-8 pt-8 border-t">
      <h2 className="text-2xl font-bold mb-8">Related Posts</h2>
      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
        {posts.map((post) => (
          <Link
            key={post.slug}
            href={`/blog/${post.slug}`}
            className="group block"
          >
            <article className="h-full flex flex-col rounded-lg border hover:border-primary/50 transition-colors overflow-hidden">
              <div className="flex-1 p-4 flex flex-col">
                <div className="flex items-center gap-2 mb-2">
                  {post.category && (
                    <Badge variant="secondary" className="text-xs">
                      {post.category}
                    </Badge>
                  )}
                  <time className="text-xs text-muted-foreground">
                    {formatDate(post.date)}
                  </time>
                </div>
                <h3 className="text-lg font-semibold mb-2 group-hover:text-primary transition-colors line-clamp-2">
                  {post.title}
                </h3>
                {post.description && (
                  <p className="text-sm text-muted-foreground mb-4 line-clamp-2 flex-1">
                    {post.description}
                  </p>
                )}
                <div className="flex items-center text-sm text-primary group-hover:underline mt-auto">
                  Read more
                  <ArrowRight className="ml-1 h-4 w-4 group-hover:translate-x-1 transition-transform" />
                </div>
              </div>
            </article>
          </Link>
        ))}
      </div>
    </section>
  )
}

Let's add social sharing buttons so readers can easily share your posts.

Creating ShareButtons Component

Create components/share-buttons.tsx:

"use client"

import { Button } from "@/components/ui/button"
import { LinkIcon, Copy, Check } from "lucide-react"
import { useState } from "react"

interface ShareButtonsProps {
  title: string
  url: string
  description?: string
}

export function ShareButtons({ title, url, description }: ShareButtonsProps) {
  const [copied, setCopied] = useState(false)

  const handleShare = (platform: string) => {
    let shareUrl = ""

    switch (platform) {
      case "x":
        shareUrl = `https://x.com/intent/tweet?text=${encodeURIComponent(title)}&url=${encodeURIComponent(url)}`
        break
      case "facebook":
        shareUrl = `https://www.facebook.com/sharer/sharer.php?u=${encodeURIComponent(url)}`
        break
      case "linkedin":
        shareUrl = `https://www.linkedin.com/sharing/share-offsite/?url=${encodeURIComponent(url)}`
        break
    }

    if (shareUrl) {
      window.open(shareUrl, "_blank", "width=600,height=400")
    }
  }

  const handleCopyLink = async () => {
    try {
      await navigator.clipboard.writeText(url)
      setCopied(true)
      setTimeout(() => setCopied(false), 2000)
    } catch (err) {
      console.error("Failed to copy link:", err)
    }
  }

  return (
    <div className="flex items-center gap-2 pt-8 border-t">
      <span className="text-sm font-medium text-muted-foreground mr-2">
        Share this post:
      </span>
      <div className="flex items-center gap-2">
        <Button
          variant="ghost"
          size="sm"
          onClick={() => handleShare("x")}
          className="h-8 w-8 p-0"
          aria-label="Share on X"
        >
          <svg
            xmlns="http://www.w3.org/2000/svg"
            width="24"
            height="24"
            viewBox="0 0 24 24"
            fill="currentColor"
            stroke="none"
            className="h-4 w-4"
          >
            <path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z"></path>
          </svg>
        </Button>
        <Button
          variant="ghost"
          size="sm"
          onClick={() => handleShare("facebook")}
          className="h-8 w-8 p-0"
          aria-label="Share on Facebook"
        >
          <svg
            xmlns="http://www.w3.org/2000/svg"
            viewBox="0 0 512 512"
            className="h-4 w-4"
            fill="currentColor"
          >
            <path d="M512 256C512 114.6 397.4 0 256 0S0 114.6 0 256C0 376 82.7 476.8 194.2 504.5V334.2H141.4V256h52.8V222.3c0-87.1 39.4-127.5 125-127.5c16 0 44.2 3.2 55.7 6.4v69.3c-6.1-.6-16.5-1-29.6-1c-42 0-58.2 15.9-58.2 57.2V256h83.6l-14.4 78.2H287v170.3C399.3 476.8 512 376 512 256z" />
          </svg>
        </Button>
        <Button
          variant="ghost"
          size="sm"
          onClick={() => handleShare("linkedin")}
          className="h-8 w-8 p-0"
          aria-label="Share on LinkedIn"
        >
          <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="currentColor" stroke="none" className="h-4 w-4">
            <path d="M19 0h-14c-2.761 0-5 2.239-5 5v14c0 2.761 2.239 5 5 5h14c2.762 0 5-2.239 5-5v-14c0-2.761-2.238-5-5-5zm-11 19h-3v-11h3v11zm-1.5-12.268c-.966 0-1.75-.79-1.75-1.764s.784-1.764 1.75-1.764 1.75.79 1.75 1.764-.783 1.764-1.75 1.764zm13.5 12.268h-3v-5.604c0-3.368-4-3.113-4 0v5.604h-3v-11h3v1.765c1.396-2.586 7-2.777 7 2.476v6.759z"></path>
          </svg>
        </Button>
        <Button
          variant="ghost"
          size="sm"
          onClick={handleCopyLink}
          className="h-8 w-8 p-0"
          aria-label="Copy link"
        >
          {copied ? (
            <Check className="h-4 w-4 text-green-600" />
          ) : (
            <LinkIcon className="h-4 w-4" />
          )}
        </Button>
      </div>
    </div>
  )
}

Step 3: Code Block Enhancement

Let's enhance code blocks with copy-to-clipboard functionality.

Creating CodeBlock Component

Create components/code-block.tsx:

'use client'

import React, { useState } from 'react'
import { Copy, Check } from 'lucide-react'
import { Button } from '@/components/ui/button'
import { cn } from '@/lib/utils'

interface CodeBlockProps extends React.HTMLAttributes<HTMLPreElement> {
  children?: React.ReactNode
}

// Helper to extract text content from React nodes
function extractTextContent(node: React.ReactNode): string {
  if (typeof node === 'string') {
    return node
  }
  if (typeof node === 'number') {
    return String(node)
  }
  if (Array.isArray(node)) {
    return node.map(extractTextContent).join('')
  }
  if (React.isValidElement(node)) {
    const props = node.props as { children?: React.ReactNode }
    if (props?.children) {
      return extractTextContent(props.children)
    }
  }
  return ''
}

export function CodeBlock({ className, children, ...props }: CodeBlockProps) {
  const [copied, setCopied] = useState(false)
  const codeContent = extractTextContent(children)

  const handleCopy = async () => {
    if (!codeContent) return

    try {
      await navigator.clipboard.writeText(codeContent)
      setCopied(true)
      setTimeout(() => setCopied(false), 2000)
    } catch (err) {
      console.error('Failed to copy code:', err)
    }
  }

  return (
    <div className="relative group">
      <pre
        className={cn('relative', className)}
        {...props}
      >
        {children}
        {codeContent && (
          <Button
            variant="ghost"
            size="icon"
            className="absolute top-2 right-2 h-8 w-8 opacity-0 group-hover:opacity-100 transition-opacity bg-neutral-800/80 hover:bg-neutral-700/80 dark:bg-neutral-700/80 dark:hover:bg-neutral-600/80 text-neutral-200 hover:text-neutral-100 border border-neutral-700/50 dark:border-neutral-600/50"
            onClick={handleCopy}
            aria-label="Copy code"
          >
            {copied ? (
              <Check className="h-4 w-4 text-green-400" />
            ) : (
              <Copy className="h-4 w-4" />
            )}
          </Button>
        )}
      </pre>
    </div>
  )
}

This replaces all <pre> tags in MDX with our enhanced CodeBlock component.

Step 4: SEO Optimization

In this step, we'll add comprehensive SEO with Open Graph tags, X Cards, and JSON-LD structured data. These will all be integrated into the complete post page file below.

Key SEO features we'll add:

Open Graph tags - For rich previews on Facebook and other platforms
X Cards - For rich previews when shared on X
Canonical URL - To prevent duplicate content issues
JSON-LD structured data - For better search engine understanding

Step 5: Complete Post Page

Now let's put everything together. Replace your app/blog/[slug]/page.tsx with this complete file that includes all the features from this part:

import { getPostData, getAllPostSlugs, getRelatedPosts } from '@/lib/posts'
import { MDXRemote } from 'next-mdx-remote/rsc'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'
import Link from 'next/link'
import { ArrowLeft } from 'lucide-react'
import { formatDate } from '@/lib/utils'
import { extractHeadings } from '@/lib/toc'
import { TableOfContents } from '@/components/table-of-contents'
import { RelatedPosts } from '@/components/related-posts'
import { ShareButtons } from '@/components/share-buttons'
import { CodeBlock } from '@/components/code-block'
import rehypeSlug from 'rehype-slug'

type PageParams = Promise<{ slug: string }>

export async function generateMetadata({
  params,
}: {
  params: PageParams
}): Promise<Metadata> {
  try {
    const { slug } = await params
    const post = await getPostData(slug)
    const url = `${process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'}/blog/${slug}`
    const image = post.image
      ? `${process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'}${post.image}`
      : `${process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'}/og-image.png`

    return {
      title: post.title,
      description: post.description,
      alternates: {
        canonical: url,
      },
      openGraph: {
        title: post.title,
        description: post.description,
        type: 'article',
        url,
        images: [
          {
            url: image,
            width: 1200,
            height: post.image ? 500 : 630,
            alt: post.title,
          },
        ],
      },
      twitter: {
        card: 'summary_large_image',
        title: post.title,
        description: post.description,
        images: [image],
      },
    }
  } catch (e) {
    return {
      title: 'Post not found',
      description: 'The post you are looking for does not exist.',
    }
  }
}

export async function generateStaticParams() {
  const posts = await getAllPostSlugs()
  return posts.map((post) => ({
    slug: post.slug,
  }))
}

export default async function PostPage({ params }: { params: PageParams }) {
  const { slug } = await params
  try {
    const post = await getPostData(slug)
    const words = post.content.split(/\s+/g).filter(Boolean).length
    const readingTime = Math.ceil(words / 200)
    const tocItems = extractHeadings(post.content)
    const relatedPosts = await getRelatedPosts(slug, 3)
    const url = `${process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'}/blog/${slug}`
    const image = post.image
      ? `${process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'}${post.image}`
      : undefined

    // JSON-LD structured data for SEO
    const jsonLd = {
      '@context': 'https://schema.org',
      '@type': 'BlogPosting',
      headline: post.title,
      description: post.description,
      image: image,
      url: url,
      datePublished: post.date,
      mainEntityOfPage: url,
      author: {
        '@type': 'Person',
        name: 'Your Name', // Replace with your name
      },
      publisher: {
        '@type': 'Organization',
        name: 'Your Blog Name', // Replace with your blog name
        logo: {
          '@type': 'ImageObject',
          url: `${process.env.NEXT_PUBLIC_SITE_URL || 'http://localhost:3000'}/logo.svg`,
        },
      },
    }

    return (
      <>
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
        />
        <div className="container mx-auto px-4 py-16">
          <div className="flex gap-8">
            <TableOfContents items={tocItems} />
            <div className="flex-1 max-w-4xl">
              <Link
                href="/blog"
                className="mb-4 flex items-center text-sm text-muted-foreground hover:underline"
              >
                <ArrowLeft className="mr-2 h-4 w-4" />
                Back to blog
              </Link>

              <h1 className="mb-2 text-3xl font-extrabold leading-tight tracking-tighter md:text-4xl">
                {post.title}
              </h1>
              <p className="mb-6 text-sm text-muted-foreground">
                {formatDate(post.date)} · {readingTime} min read
              </p>

              <article className="prose dark:prose-invert max-w-none">
                <MDXRemote
                  source={post.content}
                  options={{
                    mdxOptions: {
                      rehypePlugins: [rehypeSlug],
                    },
                  }}
                  components={{
                    pre: CodeBlock,
                  }}
                />
              </article>

              <ShareButtons
                title={post.title}
                url={url}
                description={post.description}
              />

              <RelatedPosts posts={relatedPosts} />
            </div>
          </div>
        </div>
      </>
    )
  } catch (e) {
    notFound()
  }
}

What's new compared to Part 2:

Added imports for getRelatedPosts, RelatedPosts, ShareButtons, and CodeBlock
Enhanced generateMetadata() with Open Graph and X Card metadata
Added JSON-LD structured data for search engines
Added CodeBlock component to MDX for copy-to-clipboard functionality
Added ShareButtons component after the article
Added RelatedPosts component at the end

Step 6: Additional Enhancements

Author Information

Add author display to post pages:

<div className="mb-8 flex items-center gap-3 text-sm text-muted-foreground">
  <div className="h-8 w-8 rounded-full bg-gray-300 dark:bg-gray-700 flex items-center justify-center font-bold text-lg">
    A
  </div>
  <span>By <span className="font-medium text-foreground">Your Name</span></span>
</div>

Date Formatting

We already have formatDate() in utils.ts. Make sure it's used consistently:

{formatDate(post.date)} • {readingTime} min read

Step 7: Deployment Considerations

Environment Variables

Create .env.local for development:

NEXT_PUBLIC_SITE_URL=http://localhost:3000

For production, set this to your actual domain.

Static Site Generation

Next.js automatically generates static pages at build time thanks to generateStaticParams(). This provides:

Fast page loads
Better SEO
Reduced server costs
CDN-friendly

Build Optimization

Your next.config.ts should already have:

compress: true,
images: {
  formats: ['image/webp', 'image/avif'],
  // ...
}

This ensures optimal performance.

What's Next

Congratulations! You've completed Part 3. You now have:

Related posts feature
Social share buttons
Enhanced code blocks
Comprehensive SEO

In Part 4, we'll show you how to:

Migrate from MDX files to ElmapiCMS headless CMS
Use the ElmapiCMS API for content
Set up webhooks for automatic rebuilds
Manage content through a user-friendly admin panel

How to Create a Next.js Blog - Part 2: Table of Contents, Search, and Categories

Raşit — Sun, 11 Jan 2026 12:11:12 +0000

Adding Interactive Features to Your Next.js Blog

In Part 1, we set up the foundation of your blog with a listing page. Now we'll add individual post pages, a table of contents for easy navigation, search functionality, and a category filtering system.

What You'll Build

By the end of Part 2, you'll have:

Individual blog post pages with MDX rendering
A table of contents component with active heading tracking
Client-side search functionality
Category filtering system with dedicated category pages
Enhanced blog listing with search and filters

Prerequisites

Before starting, make sure you've completed Part 1 and have:

A working Next.js blog with MDX support
shadcn/ui components installed
Sample blog posts in content/blog/
Basic understanding of React hooks (useState, useMemo)

Step 1: Creating Dynamic Post Pages

Let's create individual pages for each blog post using Next.js dynamic routes.

Updating posts.ts

Next, we need to add a function to get individual post data. Update lib/posts.ts:

export async function getPostData(slug: string): Promise<Post> {
  const fullPath = path.join(postsDirectory, `${slug}.mdx`)
  try {
    await fs.stat(fullPath)
  } catch (error) {
    throw new Error('Post not found')
  }
  const fileContents = await fs.readFile(fullPath, 'utf8')

  // Use gray-matter to parse the post metadata section
  const matterResult = matter(fileContents)

  // Combine the data with the id and content
  return {
    slug,
    title: matterResult.data.title,
    date: matterResult.data.date,
    description: matterResult.data.description,
    content: matterResult.content,
    image: matterResult.data.image,
    image_dark: matterResult.data.image_dark,
    category: matterResult.data.category,
  }
}

This function reads a specific MDX file and returns both the frontmatter and content.

Creating the Dynamic Route

Create app/blog/[slug]/page.tsx:

import { getPostData, getAllPostSlugs } from '@/lib/posts'
import { MDXRemote } from 'next-mdx-remote/rsc'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'
import Link from 'next/link'
import { ArrowLeft } from 'lucide-react'
import { formatDate } from '@/lib/utils'
import rehypeSlug from 'rehype-slug'

type PageParams = Promise<{ slug: string }>

export async function generateMetadata({
  params,
}: {
  params: PageParams
}): Promise<Metadata> {
  try {
    const { slug } = await params
    const post = await getPostData(slug)
    return {
      title: post.title,
      description: post.description,
    }
  } catch (e) {
    return {
      title: 'Post not found',
      description: 'The post you are looking for does not exist.',
    }
  }
}

export async function generateStaticParams() {
  const posts = await getAllPostSlugs()
  return posts.map((post) => ({
    slug: post.slug,
  }))
}

export default async function PostPage({ params }: { params: PageParams }) {
  const { slug } = await params
  try {
    const post = await getPostData(slug)
    const words = post.content.split(/\s+/g).filter(Boolean).length
    const readingTime = Math.ceil(words / 200) // ~200 words per minute

    return (
      <div className="container mx-auto px-4 py-16 max-w-4xl">
        <Link
          href="/blog"
          className="mb-4 flex items-center text-sm text-muted-foreground hover:underline"
        >
          <ArrowLeft className="mr-2 h-4 w-4" />
          Back to blog
        </Link>

        <h1 className="mb-2 text-3xl font-extrabold leading-tight tracking-tighter md:text-4xl">
          {post.title}
        </h1>
        <p className="mb-6 text-sm text-muted-foreground">
          {formatDate(post.date)} · {readingTime} min read
        </p>

        <article className="prose dark:prose-invert max-w-none">
          <MDXRemote
            source={post.content}
            options={{
              mdxOptions: {
                rehypePlugins: [rehypeSlug],
              },
            }}
          />
        </article>
      </div>
    )
  } catch (e) {
    notFound()
  }
}

Key features:

generateStaticParams() - Pre-generates all post pages at build time for optimal performance
generateMetadata() - Creates SEO-friendly metadata for each post
MDXRemote - Renders MDX content with React Server Components
notFound() - Shows 404 page if post doesn't exist
Reading time - Calculates estimated reading time

Adding the formatDate Utility

Let's add a utility function to format dates. Add this to lib/utils.ts:

export function formatDate(date: string): string {
  return new Date(date).toLocaleDateString('en-US', {
    year: 'numeric',
    month: 'long',
    day: 'numeric',
  })
}

This function takes a date string (like '2026-01-10') and returns a nicely formatted date (like 'January 10, 2026').

Installing Required Packages

Make sure you have the typography plugin for prose styling:

npm install @tailwindcss/typography

Next.js 16 uses Tailwind CSS v4, which configures plugins in CSS rather than a config file. Add the typography plugin to app/globals.css:

@import "tailwindcss";
@plugin "@tailwindcss/typography";

Add the @plugin line after the @import "tailwindcss" line that's already in your globals.css.

The prose class provides beautiful typography for your MDX content.

Step 2: Implementing Table of Contents

A table of contents helps readers navigate long blog posts. We'll create a component that extracts headings and highlights the active section.

Installing rehype-slug

First, install the rehype-slug package to automatically generate IDs for headings:

npm install rehype-slug

Creating the TOC Utility

Create lib/toc.ts:

export interface TocItem {
  id: string
  text: string
  level: number
}

function slugify(text: string): string {
  return text
    .toLowerCase()
    .replace(/[^\w\s-]/g, '') // Remove special characters
    .replace(/\s+/g, '-') // Replace spaces with hyphens
    .replace(/-+/g, '-') // Replace multiple hyphens with single
    .trim()
}

export function extractHeadings(content: string): TocItem[] {
  // Match markdown headings: ## Heading Text or ### Heading Text
  const headingRegex = /^(#{2,4})\s+(.+)$/gm
  const headings: TocItem[] = []
  let match

  while ((match = headingRegex.exec(content)) !== null) {
    const level = match[1].length // Number of # symbols
    const text = match[2].trim()
    const id = slugify(text)

    if (id && text) {
      headings.push({
        id,
        text,
        level,
      })
    }
  }

  return headings
}

This utility:

slugify() - Converts heading text to URL-friendly IDs (matching what rehype-slug generates)
extractHeadings() - Parses markdown headings (##, ###, ####) from the raw MDX content

Creating the Table of Contents Component

Create components/table-of-contents.tsx:

'use client'

import { useEffect, useState } from 'react'
import { cn } from '@/lib/utils'

interface TocItem {
  id: string
  text: string
  level: number
}

interface TableOfContentsProps {
  items: TocItem[]
}

export function TableOfContents({ items }: TableOfContentsProps) {
  const [activeId, setActiveId] = useState<string>('')

  useEffect(() => {
    const observer = new IntersectionObserver(
      (entries) => {
        entries.forEach((entry) => {
          if (entry.isIntersecting) {
            setActiveId(entry.target.id)
          }
        })
      },
      {
        rootMargin: '-128px 0px -66% 0px', // Account for fixed header
        threshold: 0,
      }
    )

    // Observe all heading elements
    items.forEach((item) => {
      const element = document.getElementById(item.id)
      if (element) {
        observer.observe(element)
      }
    })

    // Check scroll position to highlight "Introduction" when at top
    const handleScroll = () => {
      if (window.scrollY < 200) {
        setActiveId('')
      }
    }

    window.addEventListener('scroll', handleScroll)
    handleScroll() // Check initial position

    return () => {
      items.forEach((item) => {
        const element = document.getElementById(item.id)
        if (element) {
          observer.unobserve(element)
        }
      })
      window.removeEventListener('scroll', handleScroll)
    }
  }, [items])

  const handleClick = (e: React.MouseEvent<HTMLAnchorElement>, id?: string) => {
    e.preventDefault()
    if (id) {
      const element = document.getElementById(id)
      if (element) {
        const offset = 128 // Match scroll-margin-top
        const elementPosition = element.getBoundingClientRect().top
        const offsetPosition = elementPosition + window.pageYOffset - offset

        window.scrollTo({
          top: offsetPosition,
          behavior: 'smooth',
        })
      }
    } else {
      // Scroll to top
      window.scrollTo({
        top: 0,
        behavior: 'smooth',
      })
    }
  }

  if (items.length === 0) {
    return null
  }

  return (
    <aside className="hidden xl:block w-64 flex-shrink-0">
      <div className="sticky top-32">
        <h2 className="text-sm font-semibold text-foreground mb-4">
          Table of Contents
        </h2>
        <nav className="space-y-1.5 max-h-[calc(100vh-12rem)] overflow-y-auto">
          <a
            href="#"
            onClick={(e) => handleClick(e)}
            className={cn(
              'block text-sm transition-colors py-1 rounded-md pl-2 font-medium',
              activeId === '' || !activeId
                ? 'text-foreground font-medium bg-accent/50'
                : 'text-muted-foreground hover:text-foreground hover:bg-accent/30'
            )}
          >
            Introduction
          </a>
          {items.map((item) => (
            <a
              key={item.id}
              href={`#${item.id}`}
              onClick={(e) => handleClick(e, item.id)}
              className={cn(
                'block text-sm transition-colors py-1 rounded-md',
                item.level === 2 && 'pl-2 font-medium',
                item.level === 3 && 'pl-6 text-muted-foreground',
                item.level === 4 && 'pl-10 text-muted-foreground',
                activeId === item.id
                  ? 'text-foreground font-medium bg-accent/50'
                  : 'text-muted-foreground hover:text-foreground hover:bg-accent/30'
              )}
            >
              {item.text}
            </a>
          ))}
        </nav>
      </div>
    </aside>
  )
}

Key features:

IntersectionObserver - Tracks which heading is currently visible
Smooth scrolling - Smoothly scrolls to headings when clicked
Active state - Highlights the current section
Responsive - Hidden on smaller screens, visible on xl screens
Sticky positioning - Stays visible while scrolling

Updating the Post Page

Update app/blog/[slug]/page.tsx to include the TOC. Here's the complete updated file:

import { getPostData, getAllPostSlugs } from '@/lib/posts'
import { MDXRemote } from 'next-mdx-remote/rsc'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'
import Link from 'next/link'
import { ArrowLeft } from 'lucide-react'
import { formatDate } from '@/lib/utils'
import { extractHeadings } from '@/lib/toc'
import { TableOfContents } from '@/components/table-of-contents'
import rehypeSlug from 'rehype-slug'

type PageParams = Promise<{ slug: string }>

export async function generateMetadata({
  params,
}: {
  params: PageParams
}): Promise<Metadata> {
  try {
    const { slug } = await params
    const post = await getPostData(slug)
    return {
      title: post.title,
      description: post.description,
    }
  } catch (e) {
    return {
      title: 'Post not found',
      description: 'The post you are looking for does not exist.',
    }
  }
}

export async function generateStaticParams() {
  const posts = await getAllPostSlugs()
  return posts.map((post) => ({
    slug: post.slug,
  }))
}

export default async function PostPage({ params }: { params: PageParams }) {
  const { slug } = await params
  try {
    const post = await getPostData(slug)
    const words = post.content.split(/\s+/g).filter(Boolean).length
    const readingTime = Math.ceil(words / 200) // ~200 words per minute
    const tocItems = extractHeadings(post.content)

    return (
      <div className="container mx-auto px-4 py-16">
        <div className="flex gap-8">
          <TableOfContents items={tocItems} />
          <div className="flex-1 max-w-4xl">
            <Link
              href="/blog"
              className="mb-4 flex items-center text-sm text-muted-foreground hover:underline"
            >
              <ArrowLeft className="mr-2 h-4 w-4" />
              Back to blog
            </Link>

            <h1 className="mb-2 text-3xl font-extrabold leading-tight tracking-tighter md:text-4xl">
              {post.title}
            </h1>
            <p className="mb-6 text-sm text-muted-foreground">
              {formatDate(post.date)} · {readingTime} min read
            </p>

            <article className="prose dark:prose-invert max-w-none">
              <MDXRemote
                source={post.content}
                options={{
                  mdxOptions: {
                    rehypePlugins: [rehypeSlug],
                  },
                }}
              />
            </article>
          </div>
        </div>
      </div>
    )
  } catch (e) {
    notFound()
  }
}

What changed:

Added imports for extractHeadings, TableOfContents, and rehypeSlug
Added tocItems extraction from post content
Wrapped the layout with a flex container for the TOC sidebar
Removed max-w-4xl from the container and moved it to the content div
Added rehypeSlug plugin to MDXRemote to auto-generate heading IDs

Step 3: Adding Search Functionality

Let's add client-side search to filter posts by title and description.

Creating the BlogList Component

Create components/blog-list.tsx:

"use client"

import { useState, useMemo } from 'react'
import Link from 'next/link'
import { Input } from '@/components/ui/input'
import { Badge } from '@/components/ui/badge'
import { Search } from 'lucide-react'
import { PostMatter } from '@/lib/posts'
import { formatDate } from '@/lib/utils'

interface BlogListProps {
  posts: PostMatter[]
}

export function BlogList({ posts }: BlogListProps) {
  const [searchQuery, setSearchQuery] = useState('')

  const filteredPosts = useMemo(() => {
    if (!searchQuery.trim()) {
      return posts
    }

    const query = searchQuery.toLowerCase()
    return posts.filter(
      (post) =>
        post.title.toLowerCase().includes(query) ||
        post.description.toLowerCase().includes(query)
    )
  }, [posts, searchQuery])

  return (
    <div className="w-full">
      {/* Search Input */}
      <div className="mb-6">
        <div className="relative">
          <Search className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
          <Input
            type="text"
            placeholder="Search posts..."
            value={searchQuery}
            onChange={(e) => setSearchQuery(e.target.value)}
            className="pl-10"
          />
        </div>
      </div>

      {/* Results count */}
      {searchQuery && (
        <p className="mb-6 text-sm text-muted-foreground">
          {filteredPosts.length} {filteredPosts.length === 1 ? 'post' : 'posts'} found
        </p>
      )}

      {/* Posts List */}
      {filteredPosts.length === 0 ? (
        <div className="py-12 text-center">
          <p className="text-muted-foreground">No posts found matching your search.</p>
        </div>
      ) : (
        <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
          {filteredPosts.map((post) => (
            <Link
              href={`/blog/${post.slug}`}
              key={post.slug}
              className="group block"
            >
              <article className="h-full rounded-lg border bg-card p-6 transition-colors hover:border-primary">
                {post.category && (
                  <Badge variant="secondary" className="mb-2">
                    {post.category}
                  </Badge>
                )}
                <h2 className="mb-2 text-xl font-semibold group-hover:text-primary transition-colors">
                  {post.title}
                </h2>
                <p className="mb-4 text-sm text-muted-foreground">
                  {post.description}
                </p>
                <time className="text-xs text-muted-foreground">
                  {formatDate(post.date)}
                </time>
              </article>
            </Link>
          ))}
        </div>
      )}
    </div>
  )
}

Key features:

useState - Manages search query state
useMemo - Memoizes filtered results for performance
Case-insensitive search - Searches both title and description
Real-time filtering - Updates as you type
Empty state - Shows message when no results found

Updating the Blog Page

Now let's update app/blog/page.tsx to use the BlogList component instead of the inline grid. Replace the entire file:

import { getSortedPostsData } from '@/lib/posts'
import { BlogList } from '@/components/blog-list'
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'Blog',
  description: 'Read our latest blog posts and tutorials.',
}

export default async function Blog() {
  const posts = await getSortedPostsData()

  return (
    <div className="container mx-auto px-4 py-16">
      <div className="mb-12 text-center">
        <h1 className="text-4xl font-bold tracking-tight sm:text-6xl">
          Blog
        </h1>
        <p className="mt-6 text-lg text-muted-foreground">
          Read our latest posts and tutorials
        </p>
      </div>
      <BlogList posts={posts} />
    </div>
  )
}

What changed from Part 1:

Removed Link and Badge imports (now handled inside BlogList)
Added BlogList import
Replaced the inline <div className="grid ..."> with posts mapping with the <BlogList posts={posts} /> component

The BlogList component now handles rendering the posts grid, search functionality, and will later handle category filtering.

Step 4: Building the Category System

Now let's add category filtering with dedicated category pages.

Adding Category Functions

Update lib/posts.ts:

export async function getAllCategories(): Promise<string[]> {
  const posts = await getSortedPostsData()
  const categories = posts
    .map((post) => post.category)
    .filter((category): category is string => Boolean(category))
  return Array.from(new Set(categories)).sort()
}

export async function getPostsByCategory(category: string): Promise<PostMatter[]> {
  const posts = await getSortedPostsData()
  return posts.filter((post) => post.category === category)
}

export async function getCategoryBySlug(slug: string): Promise<string | null> {
  const categories = await getAllCategories()
  const matchedCategory = categories.find(
    (category) => slugify(category) === slug.toLowerCase()
  )
  return matchedCategory || null
}

Add the slugify utility to lib/utils.ts:

export function slugify(text: string): string {
  return text
    .toLowerCase()
    .trim()
    .replace(/[^\w\s-]/g, '') // Remove special characters
    .replace(/[\s_-]+/g, '-') // Replace spaces, underscores, and multiple hyphens with single hyphen
    .replace(/^-+|-+$/g, '') // Remove leading/trailing hyphens
}

export function getCategorySlug(category: string): string {
  return slugify(category)
}

Now add the import at the top of lib/posts.ts:

import { slugify } from '@/lib/utils'

Creating Category Pages

Create app/blog/category/[category]/page.tsx:

import { getSortedPostsData, getAllCategories, getCategoryBySlug } from '@/lib/posts'
import { getCategorySlug } from '@/lib/utils'
import { BlogList } from '@/components/blog-list'
import { notFound } from 'next/navigation'
import type { Metadata } from 'next'

type PageParams = Promise<{ category: string }>

export async function generateMetadata({
  params,
}: {
  params: PageParams
}): Promise<Metadata> {
  const { category } = await params
  const matchedCategory = await getCategoryBySlug(category)

  if (!matchedCategory) {
    return {
      title: 'Category not found',
      description: 'The category you are looking for does not exist.',
    }
  }

  return {
    title: `${matchedCategory} | Blog`,
    description: `Browse all ${matchedCategory.toLowerCase()} posts.`,
  }
}

export async function generateStaticParams() {
  const categories = await getAllCategories()
  return categories.map((category) => ({
    category: getCategorySlug(category),
  }))
}

export default async function CategoryPage({ params }: { params: PageParams }) {
  const { category } = await params
  const matchedCategory = await getCategoryBySlug(category)

  if (!matchedCategory) {
    notFound()
  }

  // Get all posts - BlogList will filter by currentCategory
  const posts = await getSortedPostsData()

  return (
    <div className="container mx-auto px-4 py-16">
      <div className="mb-12 text-center">
        <h1 className="text-4xl font-bold tracking-tight sm:text-6xl">
          {matchedCategory}
        </h1>
        <p className="mt-6 text-lg text-muted-foreground">
          Browse all {matchedCategory.toLowerCase()} posts
        </p>
      </div>
      <BlogList posts={posts} currentCategory={matchedCategory} />
    </div>
  )
}

Key point: We pass all posts to BlogList along with currentCategory. This way, BlogList can display all category filter buttons while showing only the posts from the selected category.

Adding Category Filters to BlogList

Update components/blog-list.tsx to include category filters. Here's the complete updated file:

"use client"

import { useState, useMemo } from 'react'
import Link from 'next/link'
import { Input } from '@/components/ui/input'
import { Badge } from '@/components/ui/badge'
import { Button } from '@/components/ui/button'
import { Search } from 'lucide-react'
import { PostMatter } from '@/lib/posts'
import { formatDate, getCategorySlug } from '@/lib/utils'

interface BlogListProps {
  posts: PostMatter[]
  currentCategory?: string | null
}

export function BlogList({ posts, currentCategory = null }: BlogListProps) {
  const [searchQuery, setSearchQuery] = useState('')

  // Get unique categories from posts
  const categories = useMemo(() => {
    const cats = posts
      .map((post) => post.category)
      .filter((category): category is string => Boolean(category))
    return Array.from(new Set(cats)).sort()
  }, [posts])

  const filteredPosts = useMemo(() => {
    let filtered = posts

    // Filter by category if currentCategory is set
    if (currentCategory) {
      filtered = filtered.filter((post) => post.category === currentCategory)
    }

    // Filter by search query
    if (searchQuery.trim()) {
      const query = searchQuery.toLowerCase()
      filtered = filtered.filter(
        (post) =>
          post.title.toLowerCase().includes(query) ||
          post.description.toLowerCase().includes(query)
      )
    }

    return filtered
  }, [posts, searchQuery, currentCategory])

  return (
    <div className="w-full">
      {/* Search Input */}
      <div className="mb-6">
        <div className="relative">
          <Search className="absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-muted-foreground" />
          <Input
            type="text"
            placeholder="Search posts..."
            value={searchQuery}
            onChange={(e) => setSearchQuery(e.target.value)}
            className="pl-10"
          />
        </div>
      </div>

      {/* Category Filters */}
      {categories.length > 0 && (
        <div className="mb-8">
          <div className="flex flex-wrap gap-2">
            <Link href="/blog">
              <Button
                variant={currentCategory === null ? 'default' : 'outline'}
                size="sm"
              >
                All
              </Button>
            </Link>
            {categories.map((category) => {
              const categoryUrl = `/blog/category/${getCategorySlug(category)}`
              const isActive = currentCategory === category
              return (
                <Link key={category} href={categoryUrl}>
                  <Button
                    variant={isActive ? 'default' : 'outline'}
                    size="sm"
                  >
                    {category}
                  </Button>
                </Link>
              )
            })}
          </div>
        </div>
      )}

      {/* Results count */}
      {(searchQuery || currentCategory) && (
        <p className="mb-6 text-sm text-muted-foreground">
          {filteredPosts.length} {filteredPosts.length === 1 ? 'post' : 'posts'} found
          {currentCategory && ` in "${currentCategory}"`}
        </p>
      )}

      {/* Posts List */}
      {filteredPosts.length === 0 ? (
        <div className="py-12 text-center">
          <p className="text-muted-foreground">No posts found matching your search.</p>
        </div>
      ) : (
        <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
          {filteredPosts.map((post) => (
            <Link
              href={`/blog/${post.slug}`}
              key={post.slug}
              className="group block"
            >
              <article className="h-full rounded-lg border bg-card p-6 transition-colors hover:border-primary">
                {post.category && (
                  <Badge variant="secondary" className="mb-2">
                    {post.category}
                  </Badge>
                )}
                <h2 className="mb-2 text-xl font-semibold group-hover:text-primary transition-colors">
                  {post.title}
                </h2>
                <p className="mb-4 text-sm text-muted-foreground">
                  {post.description}
                </p>
                <time className="text-xs text-muted-foreground">
                  {formatDate(post.date)}
                </time>
              </article>
            </Link>
          ))}
        </div>
      )}
    </div>
  )
}

What changed from the previous version:

Added Button import from shadcn/ui
Added getCategorySlug import from utils
Added currentCategory prop to the interface
Added categories extraction using useMemo
Updated filteredPosts to filter by category when set
Added category filter buttons section
Updated results count to show current category

What's Next

Congratulations! You've completed Part 2. You now have:

Individual post pages with MDX rendering
Table of contents with active heading tracking
Search functionality
Category filtering system

In Part 3, we'll add:

Related posts feature
Share buttons
Enhanced code blocks
SEO optimization
Image optimization

How to Create a Next.js Blog - Part 1: Setup and Basic Structure

Raşit — Sat, 10 Jan 2026 13:25:40 +0000

A Step-by-Step Guide to Building Your First Next.js Blog with MDX and shadcn/ui

In this tutorial series, you'll learn how to build a modern, feature-rich blog using Next.js, MDX for content, and shadcn/ui for beautiful components. We'll start by building the blog with local MDX files to understand the fundamentals, and then in Part 4, we'll migrate to ElmapiCMS (headless CMS) to enable content management without code changes. This approach lets you learn both MDX file-based blogging and headless CMS integration. By the end of Part 1, you'll have a working blog listing page that displays posts from MDX files.

What You'll Build
Prerequisites
Step 1: Creating the Next.js Project
Step 2: Installing and Configuring shadcn/ui
Step 3: Setting Up MDX Support
Step 4: Creating the Blog Directory Structure
Step 5: Building the Blog Listing Page
Step 6: Styling with Tailwind CSS
What's Next
Troubleshooting
Conclusion

What You'll Build

By the end of Part 1, you'll have:

A Next.js project with TypeScript configured
shadcn/ui components installed and configured
MDX support for writing blog posts
A blog listing page that displays posts from MDX files
Basic styling with Tailwind CSS
A foundation ready for advanced features in later parts

Prerequisites

Before starting, make sure you have:

Node.js 20+ installed
npm or yarn package manager
Basic knowledge of React and TypeScript
A code editor like VS Code or Cursor
Familiarity with the command line

Step 1: Creating the Next.js Project

Let's start by creating a new Next.js project with TypeScript. Open your terminal and run:

npx create-next-app@latest my-blog

When prompted "Would you like to use the recommended Next.js defaults?", select the following option:

"Yes, use recommended defaults"

This will create a new Next.js project with all the modern features we need. Once the installation is complete, navigate to your project:

cd my-blog

Project Structure Overview

Your project should now have this structure:

my-blog/
├── app/
│   ├── globals.css
│   ├── layout.tsx
│   └── page.tsx
├── public/
├── .gitignore
├── eslint.config.mjs
├── next-env.d.ts
├── next.config.ts
├── package.json
├── ...

The app/ directory is where we'll create our blog pages using Next.js App Router.

Step 2: Installing and Configuring shadcn/ui

shadcn/ui is a collection of beautifully designed, accessible React components built on top of Radix UI and Tailwind CSS. We'll use it to build our blog's UI.

Installing shadcn/ui

First, initialize shadcn/ui in your project:

npx shadcn@latest init

You'll be prompted with a question:

Which color would you like to use as the base color? → Select one of the default colors

This creates a components.json file in your project root that configures shadcn/ui.

Installing Initial Components

Now let's install the components we'll need for Part 1:

npx shadcn@latest add button input badge

This installs:

Button - For interactive elements
Input - For search functionality (we'll use this in Part 2)
Badge - For displaying categories

The components will be added to components/ui/ and you can import them like this:

import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { Badge } from '@/components/ui/badge'

Understanding components.json

Your components.json file should look something like this:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "iconLibrary": "lucide",
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils",
    "ui": "@/components/ui",
    "lib": "@/lib",
    "hooks": "@/hooks"
  },
  "registries": {}
}

This configuration ensures that shadcn/ui components work correctly with your project setup.

Step 3: Setting Up MDX Support

MDX allows you to write JSX in your Markdown files, making it perfect for blog posts. We'll use next-mdx-remote to render MDX content and gray-matter to parse frontmatter.

Note: We're starting with MDX files to understand how content management works at a fundamental level. In Part 4, we'll migrate to ElmapiCMS headless CMS, which will replace reading from MDX files with API calls. The content structure and rendering approach will remain similar, but content will be managed through an admin panel instead of files.

Installing Required Packages

Install the necessary packages:

npm install next-mdx-remote gray-matter globby remark-gfm

next-mdx-remote - Renders MDX content in Next.js
gray-matter - Parses frontmatter from MDX files
globby - Finds MDX files in directories
remark-gfm - GitHub Flavored Markdown support

Step 4: Creating the Blog Directory Structure

Now let's set up the directory structure for storing blog posts. Create a content/blog/ directory in your project root:

mkdir -p content/blog

Understanding Frontmatter Structure

Each MDX blog post will have frontmatter (metadata) at the top of the file. Here's the structure we'll use:

---
title: 'Your Post Title'
date: '2026-01-10'
description: 'A brief description of your post'
image: '/img/blog/your-image.webp'
image_dark: '/img/blog/your-image-dark.webp'
category: 'Tutorial'
---

title - The post title
date - Publication date (YYYY-MM-DD format)
description - SEO description and post excerpt
image - Featured image URL (optional)
image_dark - Dark mode variant (optional)
category - Post category (optional)

Creating Sample MDX Files

Create a few sample blog posts to test with. Create content/blog/first-post.mdx:

---
title: 'Welcome to My Blog'
date: '2026-01-10'
description: 'This is my first blog post using Next.js and MDX!'
category: 'Getting Started'
---

# Welcome to My Blog

This is my first blog post. I'm using **Next.js** and **MDX** to create a modern blog.

## What I'm Learning

- Next.js App Router
- MDX for content
- shadcn/ui components

## Next Steps

I'll be adding more features in the next parts of this tutorial series.

Create another sample post content/blog/second-post.mdx:

---
title: 'Building with Next.js'
date: '2026-01-10'
description: 'Exploring the power of Next.js for building modern web applications.'
category: 'Tutorial'
---

# Building with Next.js

Next.js is a powerful React framework that makes building web applications easy.

## Key Features

- Server-side rendering
- Static site generation
- API routes
- Image optimization

Step 5: Building the Blog Listing Page

Now let's create the utility functions to read MDX files and build the blog listing page.

Creating Posts Utility Functions

Create lib/posts.ts:

import { globby } from 'globby'
import matter from 'gray-matter'
import fs from 'fs/promises'
import path from 'path'

export interface Post {
  slug: string
  title: string
  date: string
  description: string
  content: string
  image?: string
  image_dark?: string
  category?: string
}

export type PostMatter = Omit<Post, 'content'>

const postsDirectory = path.join(process.cwd(), 'content/blog')

export async function getSortedPostsData(): Promise<PostMatter[]> {
  const filePaths = await globby('*.mdx', { cwd: postsDirectory })
  const allPostsData = await Promise.all(
    filePaths.map(async (filePath: string) => {
      const slug = filePath.replace(/\.mdx$/, '')
      const fullPath = path.join(postsDirectory, filePath)
      const fileContents = await fs.readFile(fullPath, 'utf8')

      // Use gray-matter to parse the post metadata section
      const matterResult = matter(fileContents)

      // Combine the data with the id
      return {
        slug,
        title: matterResult.data.title,
        date: matterResult.data.date,
        description: matterResult.data.description,
        image: matterResult.data.image,
        image_dark: matterResult.data.image_dark,
        category: matterResult.data.category,
      } as PostMatter
    }),
  )
  // Sort posts by date (newest first)
  return allPostsData.sort((a: PostMatter, b: PostMatter) => {
    if (a.date < b.date) {
      return 1
    } else {
      return -1
    }
  })
}

export async function getAllPostSlugs() {
  const filePaths = await globby('*.mdx', { cwd: postsDirectory })
  return filePaths.map((filePath) => {
    return {
      slug: filePath.replace(/\.mdx$/, ''),
    }
  })
}

This file exports:

Post interface - TypeScript type for a complete post
PostMatter type - Post without content (for listings)
getSortedPostsData() - Gets all posts sorted by date
getAllPostSlugs() - Gets all post slugs (for static generation)

Creating the Blog Page

Create app/blog/page.tsx:

import { getSortedPostsData } from '@/lib/posts'
import type { Metadata } from 'next'
import Link from 'next/link'
import { Badge } from '@/components/ui/badge'

export const metadata: Metadata = {
  title: 'Blog',
  description: 'Read our latest blog posts and tutorials.',
}

export default async function Blog() {
  const posts = await getSortedPostsData()

  return (
    <div className="container mx-auto px-4 py-16">
      <div className="mb-12 text-center">
        <h1 className="text-4xl font-bold tracking-tight sm:text-6xl">
          Blog
        </h1>
        <p className="mt-6 text-lg text-muted-foreground">
          Read our latest posts and tutorials
        </p>
      </div>

      <div className="grid gap-6 md:grid-cols-2 lg:grid-cols-3">
        {posts.map((post) => (
          <Link
            key={post.slug}
            href={`/blog/${post.slug}`}
            className="group block"
          >
            <article className="h-full rounded-lg border bg-card p-6 transition-colors hover:border-primary">
              {post.category && (
                <Badge variant="secondary" className="mb-2">
                  {post.category}
                </Badge>
              )}
              <h2 className="mb-2 text-xl font-semibold group-hover:text-primary transition-colors">
                {post.title}
              </h2>
              <p className="mb-4 text-sm text-muted-foreground">
                {post.description}
              </p>
              <time className="text-xs text-muted-foreground">
                {new Date(post.date).toLocaleDateString('en-US', {
                  year: 'numeric',
                  month: 'long',
                  day: 'numeric',
                })}
              </time>
            </article>
          </Link>
        ))}
      </div>
    </div>
  )
}

This page:

Fetches all posts using getSortedPostsData()
Displays them in a responsive grid
Shows category badges
Links to individual post pages (we'll create these in Part 2)

Testing the Blog Page

Start your development server:

npm run dev

Visit http://localhost:3000/blog to see your blog listing page. You should see your sample posts displayed in a grid.

Step 6: Styling with Tailwind CSS

Tailwind CSS is already configured in your Next.js project. The blog page uses Tailwind utility classes for styling.

Understanding the Styling

The blog page uses:

container - Centers content with max-width
grid - Creates a responsive grid layout
gap-6 - Adds spacing between grid items
md:grid-cols-2 - 2 columns on medium screens
lg:grid-cols-3 - 3 columns on large screens
hover:border-primary - Changes border color on hover
text-muted-foreground - Uses theme-aware muted text color

Customizing Colors

shadcn/ui uses CSS variables for theming. You can customize colors in app/globals.css. The default theme includes:

Primary colors
Secondary colors
Muted colors
Accent colors
Destructive colors

What's Next

Congratulations! You've completed Part 1. You now have:

A Next.js project with TypeScript
shadcn/ui components installed
MDX support configured
A working blog listing page

In Part 2, we'll add:

Individual post pages with MDX rendering
Table of contents component
Search functionality
Category filtering system

In Part 4, we'll migrate from MDX files to ElmapiCMS headless CMS, which will enable:

Content management through an admin panel (no code changes needed)
Multi-user collaboration
API-based content delivery
Automatic rebuilds via webhooks

This migration will replace the MDX file reading with API calls, but all the features we build will continue to work seamlessly.

Why I Ended Up Building My Own Headless CMS

Raşit — Fri, 28 Nov 2025 06:00:03 +0000

For almost twenty years, my work revolved around client projects. Every new website, app, or internal tool had one thing in common: I had to build some kind of CMS backend for it.

Sometimes it was custom Laravel panels, sometimes it was WordPress with custom post types, sometimes hybrid setups. Over time, the problems repeated themselves.

Here are the main pain points that pushed me to build my own headless CMS.

1. Every project needed a CMS, but every CMS had to be rebuilt

Even when the requirements were similar, I kept writing the same migrations, controllers, CRUD logic, validation, media handling, user management, and API endpoints.

I tried to template it, but templates always drift. They solve the first few steps but not the ongoing complexity.

I wanted a backend where:

projects could be created in minutes
collections and fields didn’t require writing migrations
APIs were generated automatically
I could skip the entire “bootstrap phase” of backend development

2. WordPress and traditional CMSs didn’t fit modern workflows

WordPress can do a lot, but once you’re working with Vue, React, or a custom single page app, the friction grows.

I wanted a backend that didn’t care about what frontend framework I chose.

Use React? Fine.

Use Vue? Fine.

Use Next, Nuxt, Svelte, plain JS, or even mobile apps? Same API.

A single backend powering any frontend with no extra plugins, no weird data structures, no custom routing hacks.

3. Multi project support is rare

Most CMS solutions assume one site per install.

My workflow never worked like that. I often needed:

multiple client projects
a shared admin user system
isolated data per project
the ability to quickly create, test, or destroy projects

A multi project architecture was essential for me, and almost no lightweight CMS offered it.

4. I wanted consistency in API design

Every custom API I built had slightly different patterns. Different naming, different filtering operators, different pagination logic.

Over time this creates chaos.

I wanted:

consistent REST endpoints
predictable filtering and sorting
predictable responses
token-based access control that didn’t require rewriting policies every time

5. Speed of setup matters

When you work on client projects, the faster you get to “working prototype,” the better.

A backend setup that takes an hour is already too slow.

I wanted something I could install on shared hosting, VPS, or anything that runs PHP, and start building immediately.

After repeating the same frustrations over many years, I started building a tool for myself. It grew, improved, and eventually became ElmapiCMS.

I’ll share more about the architecture and decisions behind it in follow-up posts, but this post captures the core reasons it exists.

Forem: Raşit

I finally launched the SaaS version of my headless CMS

Introducing NomaCMS

What NomaCMS is

Structured content modeling

A REST API and a typed JavaScript SDK

Assets, webhooks, and localization

Project authentication for your users

Built-in AI, without the lock-in

AI coding tools, first class

Getting started

I turned my headless CMS into an AI-native CMS. Here’s what happened.

1. From text generation to schema-aware AI

2. Conversational schema creation

3. One-click translation

4. MCP server for AI-driven workflows

5. The reality check

How to Create a Next.js Blog - Part 3: Advanced Features

What You'll Build

Prerequisites

Step 1: Related Posts Feature

Implementing getRelatedPosts()

Creating the RelatedPosts Component

Step 2: Share Buttons Component

Creating ShareButtons Component

Step 3: Code Block Enhancement

Creating CodeBlock Component

Step 4: SEO Optimization

Step 5: Complete Post Page

Step 6: Additional Enhancements

Author Information

Date Formatting

Step 7: Deployment Considerations

Environment Variables

Static Site Generation

Build Optimization

What's Next

How to Create a Next.js Blog - Part 2: Table of Contents, Search, and Categories

What You'll Build

Prerequisites

Step 1: Creating Dynamic Post Pages

Updating posts.ts

Creating the Dynamic Route

Adding the formatDate Utility

Installing Required Packages

Step 2: Implementing Table of Contents

Installing rehype-slug

Creating the TOC Utility

Creating the Table of Contents Component

Updating the Post Page

Step 3: Adding Search Functionality

Creating the BlogList Component

Updating the Blog Page

Step 4: Building the Category System

Adding Category Functions

Creating Category Pages

Adding Category Filters to BlogList

What's Next

How to Create a Next.js Blog - Part 1: Setup and Basic Structure

Table of Contents

What You'll Build

Prerequisites

Step 1: Creating the Next.js Project

Project Structure Overview

Step 2: Installing and Configuring shadcn/ui

Installing shadcn/ui

Installing Initial Components

Understanding components.json

Step 3: Setting Up MDX Support

Installing Required Packages

Step 4: Creating the Blog Directory Structure

Understanding Frontmatter Structure

Creating Sample MDX Files

Step 5: Building the Blog Listing Page

Creating Posts Utility Functions

Creating the Blog Page

Testing the Blog Page

Step 6: Styling with Tailwind CSS

Understanding the Styling

Customizing Colors