DEV Community: Raşit

Multilingual sites with a headless CMS: locales, translation groups, and AI translate

Raşit — Fri, 17 Jul 2026 10:42:14 +0000

Originally published on nomacms.com. I work on NomaCMS.

Most i18n CMS guides stop at field-level vs document-level locales. Fair comparison, but it skips the boring parts: adding languages to a project, keeping translations linked, fetching the right locale in Next.js, and refreshing cached pages when someone publishes.

This walkthrough covers that stack with NomaCMS: project locales, translation groups, SDK fetch-by-locale, dashboard AI translate, and a webhook hook for revalidation.

Document-level locales vs field-level

Two common patterns:

Field-level: one entry, fields like title_en and title_de
Document-level: one entry per language, linked as translations

NomaCMS uses document-level locales. Each entry has a locale code. Related translations share a translation group, so your app can swap languages or call translation_locale in the SDK without hardcoding UUID maps.

That fits marketing sites well: editors work in one language at a time, publish state stays per locale, and the frontend just passes locale into content.list or content.get.

Setup: locales and a Pages collection

In the dashboard: Project Settings → Localization → Add a Locale (e.g. de).
Create a Pages collection (pages) with title (Text), slug (Slug from title), body (Rich Text).
Create and publish an English page.

Each locale is its own row. English and German are separate entries, not duplicate fields.

When you create via API/SDK, pass locale on the body. Omit it and the API falls back to the project default.

Translation groups

Open the English entry. With multiple locales configured, the sidebar shows Translations.

From the dialog you can:

Translate with AI: draft in the target locale, translate text fields, copy media/relations, generate slug, link the group
Create: blank draft in that locale, linked
Select: link an existing entry in the same collection

Link from code when you need to:

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

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

await noma.content.linkTranslation("pages", englishUuid, {
  translation_entry_uuid: germanUuid,
})

Fetch a linked translation without storing both UUIDs:

const germanPage = await noma.content.get("pages", englishUuid, {
  state: "published",
  translation_locale: "de",
})

Both entries must be in the same collection with different locales.

Fetch by locale in Next.js

Keep the API key on the server. Minimal list page with a [locale] segment:

// app/[locale]/pages/page.tsx
import { createClient } from "@nomacms/js-sdk"

type Props = { params: Promise<{ locale: string }> }

export default async function PagesIndex({ params }: Props) {
  const { locale } = await params
  const noma = createClient({
    projectId: process.env.NOMA_PROJECT_ID!,
    apiKey: process.env.NOMA_API_KEY!,
  })

  const result = await noma.content.list("pages", {
    state: "published",
    locale,
    sort: "created_at:desc",
  })

  const pages = "data" in result ? result.data : result

  return (
    <ul>
      {pages.map((page) => (
        <li key={page.uuid}>
          <a href={`/${locale}/pages/${page.uuid}`}>
            {String(page.fields?.title ?? page.uuid)}
          </a>
        </li>
      ))}
    </ul>
  )
}

Language switcher on a detail page:

// app/[locale]/pages/[id]/page.tsx
import { notFound } from "next/navigation"
import { createClient } from "@nomacms/js-sdk"

type Props = { params: Promise<{ locale: string; id: string }> }

export default async function PageDetail({ params }: Props) {
  const { locale, id } = await params
  const noma = createClient({
    projectId: process.env.NOMA_PROJECT_ID!,
    apiKey: process.env.NOMA_API_KEY!,
  })

  try {
    const page = await noma.content.get("pages", id, {
      state: "published",
      locale,
    })

    let alternateHref: string | null = null
    try {
      const alt = await noma.content.get("pages", id, {
        state: "published",
        translation_locale: locale === "en" ? "de" : "en",
      })
      alternateHref = `/${alt.locale}/pages/${alt.uuid}`
    } catch {
      // no linked translation
    }

    return (
      <article>
        <h1>{String(page.fields?.title ?? "")}</h1>
        {alternateHref && <p><a href={alternateHref}>Switch language</a></p>}
      </article>
    )
  } catch {
    notFound()
  }
}

Nuxt? Same locale param in a Nitro route:

// server/api/pages/[locale].get.ts
export default defineEventHandler(async (event) => {
  const locale = getRouterParam(event, "locale")
  const noma = useNomaCMSServerClient()
  return noma.content.list("pages", { state: "published", locale })
})

Full setup: Next.js guide · Nuxt guide

AI translate in the dashboard

Open the English entry → Translations → Translate with AI next to de.

The UI streams progress field by field. It creates a draft (for regular collections), links the translation group, translates text / longtext / richtext while keeping HTML structure, copies media and relations, and generates slugs from translated titles.

Review, edit, publish. Dashboard-only feature, not a public API.

Webhooks for revalidation

When an editor publishes in any locale, poke Next.js with a content.published webhook. Register from Project Settings → Webhooks or the SDK, then verify X-Webhook-Signature (HMAC-SHA256 of the body) in a Route Handler and call revalidatePath. Webhook docs

Links

Questions welcome in the comments.

Best Way to Build a Modern Website in 2026: Static Sites + Headless CMS

Raşit — Thu, 02 Jul 2026 14:01:44 +0000

WordPress and Webflow are still the right call when the client has no developer on retainer, expects in-browser editing without a separate frontend repo, or depends on plugins and integrations that only exist in those ecosystems. Forcing Jamstack on those clients creates friction that shows up in support tickets six months later.

When the agency can standardize on frontend templates and a content API, the static-first plus headless CMS pattern scales better across clients.

Four paths in 2026

The market in 2026 is fragmented by role, not by one dominant platform. Each path has a legitimate place in agency work.

Path 1: AI-augmented no-code

Examples: Framer, Wix, Hostinger AI builder, Durable

Best for agencies when: speed matters more than ownership, the client has no development budget, and the site is a simple presence or campaign landing page.

Trade-off: limited portability, vendor lock-in, and weak reuse of the same codebase across multiple clients. The AI step accelerates the first draft; ongoing edits still happen inside that vendor's editor.

Path 2: Visual pro builder

Examples: Webflow

Best for agencies when: the deliverable is a design-led marketing site, marketers need self-serve editing after handover, and hosting, SSL, and CDN are acceptable as platform fees.

Trade-off: cost scales with traffic and seats; complex integrations and deeply custom application logic hit a ceiling sooner than a code-first stack. Code export exists on some plans but dynamic CMS features do not always survive a move.

Path 3: Classic CMS

Examples: WordPress (block themes, Elementor, or custom themes)

Best for agencies when: the client expects WordPress, needs a broad plugin library, or runs a content operation that already lives in WP admin.

Trade-off: security patches, plugin conflicts, and performance tuning become ongoing responsibilities. A well-cached WordPress site can perform well; a neglected one becomes a maintenance liability.

Path 4: Modern dev stack

Examples: Astro, Next.js, or Nuxt frontend + headless CMS (NomaCMS, ElmapiCMS, Contentful, Sanity, Strapi, Payload, Directus, Storyblok, and others)

Best for agencies when: reusable templates, strong performance, and a clean separation between content and presentation matter, especially across several client sites on similar architecture.

Trade-off: requires developer capacity for the frontend and integration work. The CMS choice affects editor experience, hosting cost, and whether one installation can serve many clients.

Paths 1–3 are valid for specific briefs. Path 4 is the focus of the rest of this guide because it is the pattern agencies can productize: one template repo per framework, one CMS operations model, many client frontends.

Recommended pattern: static-first + headless CMS

The architecture agencies reuse most often in 2026 looks like this:

Editors update structured content in a headless CMS admin.
The CMS exposes a content API (REST or GraphQL).
The frontend fetches content at build time (SSG), on a schedule (ISR), or per request (SSR) for the pages that need it.
Public pages ship as HTML from an edge CDN; only interactive regions load JavaScript where necessary.

This is the practical meaning of "Jamstack" or "composable" in agency delivery: not a brand name, but pre-rendered HTML plus APIs plus selective hydration.

Why static-first

Static and hybrid sites deliver predictable performance: no database round-trip on every page view for marketing content. Security surface area shrinks when the public site is files on a CDN. Hosting costs stay low for brochure and blog traffic patterns.

The islands architecture trend — render most of the page as HTML, hydrate only widgets that need client state — keeps JavaScript budgets under control. That matters for Core Web Vitals and for clients who care about mobile performance on average connections.

When to add SSR or ISR

Pure static generation fits content that changes infrequently or can wait for the next deploy. Add incremental static regeneration, on-demand revalidation, or server-side rendering when:

editors publish several times per week and cannot wait for a full rebuild pipeline;
preview URLs must show draft content;
localized routes or large entry counts make full rebuilds slow.

SEO and release discipline for headless frontends — canonicals, sitemaps, metadata — should be treated as a gate before client handover, not an afterthought.

Framework picker for agencies

The frontend choice should follow team skills and the client's interaction requirements — not hype cycles.

Astro

Fits: content-heavy marketing sites, blogs, documentation-style hubs, portfolios.

Strengths: minimal client JavaScript by default, fast builds, strong content-focused developer experience.

Agency note: pair with a headless CMS when marketers edit copy; use Markdown in Git only when the client accepts developer-mediated updates.

Next.js

Fits: marketing sites that share a codebase with app-like features, teams already on React, projects needing App Router and hybrid rendering.

Strengths: large ecosystem, mature deployment on Vercel and other hosts, ISR and server components for mixed static and dynamic routes.

Agency note: avoid shipping a full client-side SPA when most routes are static marketing pages.

Nuxt

Fits: Vue teams, i18n-heavy sites, agencies standardized on the Vue ecosystem.

Strengths: file-based routing, solid SSR and SSG story, good fit for multilingual client sites.

Vue (without Nuxt)

Fits: smaller Vue SPAs or embedded apps where a full Nuxt stack is more than the brief requires.

SvelteKit

Fits: teams invested in Svelte, niche projects where bundle size and simplicity matter.

Strengths: growing framework; smaller hiring pool and package ecosystem than React or Vue.

Headless CMS picker for agencies

CMS selection for agency work should be evaluated on axes that show up in monthly operations — not on feature checklists copied from vendor homepages.

Criterion	What to ask
Hosting model	Cloud SaaS vs self-hosted on agency infrastructure
Multi-project fit	One install for many clients, or one install per client
Editor UX	Can the client's marketer publish without filing a ticket
API and SDKs	REST or GraphQL, TypeScript clients, webhook support
Cost at scale	Total cost across five to ten client sites over two years
Operational burden	Updates, memory use, plugin ecosystems, backup routines

NomaCMS

NomaCMS is a managed, AI-native headless CMS. Structured content, a REST API, and a JavaScript SDK ship without running a CMS server on agency infrastructure. Built-in AI assists with writing, translation, and inline field editing; an MCP server connects Cursor, Claude Code, and other AI editors. Separate projects per client keep schema, entries, assets, and API keys isolated in the cloud. Paid plans add project auth, webhooks, locales, team workspaces, and versioning. Global CDN handles asset delivery. Plans start at $15 per month after a 7-day free trial.

Agency fit: teams that want hosted delivery, predictable SaaS pricing, and AI-first editorial workflows without VPS maintenance. Strong when the agency prefers cloud ops over self-hosting.

ElmapiCMS

Self-hosted headless CMS on Laravel with multi-project support from one installation — separate content, API keys, and users per client. One-time licensing ($70) rather than per-seat SaaS fees suits agencies running several similar client sites on their own server. PHP-based hosting tends toward lower idle memory than many Node CMS stacks. Editor UI is React-based; delivery is API-first for Astro, Next.js, Nuxt, and other frontends.

Agency fit: teams comfortable running infrastructure who want unlimited projects from a single install and predictable long-term cost at scale.

Contentful

Enterprise-grade cloud CMS with strong API tooling and personalization options. Editorial workflows and roles are mature. Cost scales with usage and seats — reasonable for larger clients, expensive when multiplied across many small sites.

Sanity

Content Lake model, real-time collaboration, and deep customization for developer-heavy teams. Strong when editors and developers share one studio daily. Pricing and schema design complexity deserve upfront planning.

Storyblok

Visual editor and marketer-friendly page building on top of headless delivery. Good fit when clients want component-based editing without touching code. Enterprise features and AI-assisted workflows are increasingly part of the pitch.

Strapi

Popular self-hosted Node.js CMS with a large plugin ecosystem. Flexible content types; each client traditionally meant another installation unless architecture is carefully designed. Memory consumption on small VPS instances is a known planning factor.

Payload

TypeScript-first, developer-oriented, often self-hosted. Strong when the agency wants code-adjacent schema and full data ownership. Requires Node operations competence.

Directus

Database-first headless layer over SQL databases. Flexible for teams that want direct data access and self-hosting. Editor experience differs from purpose-built marketing CMS products.

For managed cloud delivery with AI workflows, see NomaCMS and its CMS for agencies guide.

Worked example: agency stack with ElmapiCMS

Scenario: an agency delivers a marketing site and blog for Client A. Clients B and C are queued on similar architecture. The agency wants one CMS operations model, reusable Astro templates, and clear handoff boundaries.

Stack: Astro frontend, ElmapiCMS, deploy to any edge-friendly host (Vercel, Netlify, or Cloudflare Pages).

Step 1: One CMS, isolated projects

Provision one ElmapiCMS installation on agency infrastructure. Create a separate project for Client A with its own collections, API keys, and user accounts. Client B and C receive their own projects on the same instance when their builds start.

This mirrors a multi-client CMS workflow: one update cycle, one backup target, no cross-client data leakage.

Step 2: Minimum content model for launch

Resist over-modeling before go-live. A practical launch schema includes:

Site settings — logo, default SEO, navigation, footer links
Pages — structured marketing URLs (home, about, pricing)
Blog posts — if the brief includes a blog

Defer team directories, complex relational catalogs, and localization until phase two.

Step 3: Reuse the agency template

Clone the agency's Astro + headless CMS starter for Client A. Replace API keys, environment variables, and branding tokens. The frontend repo structure stays identical across clients; only the content API endpoint and keys change.

Step 4: Publish flow

On publish, either trigger a build webhook from the CMS to the hosting provider or use on-demand revalidation if the frontend supports it.

Step 5: Client handoff

Document what the client may edit in the CMS (copy, images, blog posts, navigation labels) versus what remains in code (layout components, new page types, design system changes). Clear boundaries prevent "small tweak" requests from becoming undeployed frontend changes.

This pattern works when the agency has frontend developers, clients need a marketer-friendly admin, and running ten separate CMS servers is not sustainable.

Paths at a glance

Path	Time to first launch	Client edit experience	Reuse across clients	Performance ceiling	Typical ops cost	Best agency use case
AI no-code	Fastest	Guided in vendor UI	Low	Medium	Low-medium	One-off microsites, speed over ownership
Webflow	Fast	Strong visual editor	Medium (clone projects)	High for marketing sites	Medium-high	Design-led marketing, marketer self-serve
WordPress	Medium	Familiar block editor	Medium (themes, multisite)	Medium-high with tuning	Medium	Plugin-heavy sites, WP-native clients
Static + headless CMS	Medium (first template slower)	CMS admin	High (templates + API)	Highest	Low-medium (self-hosted)	Retainer clients, multi-site agencies

"Ops cost" is qualitative: SaaS platforms trade cash for reduced server work; self-hosted stacks trade server time for license savings at scale.

Client scenarios

SaaS landing page and changelog

A B2B startup updates hero copy and ships product changelog entries weekly. Astro + headless CMS keeps the marketing site fast while marketers edit structured sections and posts without touching Git. ISR or webhook-triggered rebuilds keep publish latency acceptable.

Developer portfolio and case studies

A consultancy refreshes case studies quarterly. Astro or Nuxt with infrequent builds fits well. If the client later wants self-serve case study publishing, add CMS collections without rewriting the frontend architecture.

Multi-client agency retainer

An agency runs eight client marketing sites on similar layouts. NomaCMS (managed cloud, one project per client) or ElmapiCMS (self-hosted, one install) plus per-client Astro repos keeps CMS ops lean. New clients clone the frontend template; billing stays predictable.

Client insists on in-browser editing, no dev budget

A local business wants to change text and images themselves and will not pay for ongoing development. Webflow or WordPress is the honest recommendation. Jamstack adds cost and friction when no one maintains the frontend repository.

Neutrality on this fourth scenario builds trust: the agency is advising on fit, not on standardizing every client into one stack.

Baselines every stack needs in 2026

Path choice does not exempt a site from fundamentals. Every delivery — including static and headless — should meet these baselines before launch:

Core Web Vitals: LCP at or below 2.5 seconds, INP at or below 200 milliseconds, CLS below 0.1 (75th percentile field data where available).
Semantic HTML: meaningful heading hierarchy, landmarks, and crawlable links — not div-only layouts for primary content.
Structured data: JSON-LD that matches visible content (Article, FAQPage, BreadcrumbList where appropriate). Mismatched schema hurts trust and rich-result eligibility.
Accessibility: WCAG 2.2 AA as a release gate — keyboard navigation, focus states, sufficient contrast.
AI and search visibility: clear question-and-answer content, accurate metadata, and stable URLs so both search engines and answer engines can cite the site reliably.

These baselines are path-agnostic. A fast Jamstack site with broken canonicals still loses visibility; a Webflow site that hits Vitals targets still wins.

What is it like to create software in the AI era?

Raşit — Tue, 21 Apr 2026 14:54:25 +0000

You still start with an idea. Something annoys you, or you see a gap, or you just want a thing to exist that doesn’t. That part hasn’t changed.

What has changed is how quickly the idea runs into reality. It’s less “can we build this?” and more “why would anyone care, and how would they even find it?” Models and copilots can spit out code and copy that looks fine on the first pass. The bottleneck moved. It’s less about typing speed and more about taste, structure, and knowing what not to ship.

Discovery is weird now too. Traditional search still exists, but it’s not the only front door it used to be. People get pulled in through feeds, recommendations inside tools, AI summaries, word of mouth, or whatever their stack already ships with. So you end up shaping the idea twice: once for the product, and once for the world it has to live in. Not in a sleazy way. Just honestly. If nobody is going to stumble on you through a five word Google query, you need another path: integrations, APIs, community, partnerships, or a problem so sharp people go looking for the category even when they don’t know your name yet.

That can feel cynical if you let it. Like you’re not building what you believe in, you’re building what fits. I don’t think it has to be that bleak. It’s more like editing. You still have a point of view. You’re just forced to say it in fewer moves.

Then there’s the crowded room. Do we even need new software? There is already a lot of everything. And yeah, sometimes the answer is no. Another thin wrapper on top of a model is not a company, it’s a weekend. The stuff that still feels worth doing is usually narrower: a specific pain big players ignore, data and permissions that need to stay sane when generation is cheap, or a workflow that has to stay reliable even when the fun parts are automated.

I swing between optimistic and skeptical about all of this, often in the same afternoon. On good days, cheap generation is freeing. You spend time on the fuzzy human stuff: who this is for, what “good enough” looks like, what breaks if you’re wrong. On bad days, it feels like everything is a remix and you’re shouting into a hallway full of people selling the same hallway.

If you’re a founder, a buyer, or someone who just ships things, the questions end up similar even if the vocabulary changes. Who is actually stuck on a random Tuesday? What would they use if you vanished? What would make them switch anyway? If you can’t answer those without squinting, the problem isn’t AI. It’s clarity.

So creating software in this era is a bit stranger, a bit faster, and a lot more honest about distribution. You’re not the only person who can code anymore. You might still be one of the few people stubborn enough to hold a standard when the tools say “done.”

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.

DEV Community: Raşit

Multilingual sites with a headless CMS: locales, translation groups, and AI translate

Document-level locales vs field-level

Setup: locales and a Pages collection

Translation groups

Fetch by locale in Next.js

AI translate in the dashboard

Webhooks for revalidation

Links

Best Way to Build a Modern Website in 2026: Static Sites + Headless CMS

Four paths in 2026

Path 1: AI-augmented no-code

Path 2: Visual pro builder

Path 3: Classic CMS

Path 4: Modern dev stack

Recommended pattern: static-first + headless CMS

Why static-first

When to add SSR or ISR

Framework picker for agencies

Astro

Next.js

Nuxt

Vue (without Nuxt)

SvelteKit

Headless CMS picker for agencies

NomaCMS

ElmapiCMS

Contentful

Sanity

Storyblok

Strapi

Payload

Directus

Worked example: agency stack with ElmapiCMS

Step 1: One CMS, isolated projects

Step 2: Minimum content model for launch

Step 3: Reuse the agency template

Step 4: Publish flow

Step 5: Client handoff

Paths at a glance

Client scenarios

SaaS landing page and changelog

Developer portfolio and case studies

Multi-client agency retainer

Client insists on in-browser editing, no dev budget

Baselines every stack needs in 2026

What is it like to create software in the AI era?

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