How I Built My Portfolio with Next.js and Sanity CMS (And What I Learned)

Every developer eventually reaches a point where they look at their portfolio and think — this doesn't feel like me anymore.

That's where I was. I wanted something that wasn't just a static resume with links. I wanted a real product — something I'd actually be proud to send to clients.

So I rebuilt everything from scratch. This is the honest breakdown of how I did it, what I used, and what I learned.

The Stack at a Glance

Why I Ditched MDX Files

My previous setup stored blog posts as .mdx files in a /content folder. It worked — until it didn't.

Project Structure

Here's how the blog-related code is organized in the repo:

Step 1 — Setting Up the Sanity Client

pnpm add next-sanity @sanity/image-url

Step 2 — Writing GROQ Queries

GROQ is Sanity's query language. It's not hard, but it's different — the first hour feels strange if you're used to SQL or GraphQL.

*[_type == "blog"] | order(publishedAt desc) {
  _id,
  slug,
  title,
  shortDescription,
  publishedAt,
  readingTime,
  categories,
  coverImage {
    asset->{ url }
  }
}

Step 3 — Dynamic Routing

The blog uses Next.js file-based routing. The file at app/blog/[slug]/page.tsx handles every individual post. Two critical exported functions power the whole thing:

generateStaticParams SSG

Tells Next.js to pre-render all blog pages at build time. Without this, every page load hits Sanity's API. With it, pages are served from the CDN.

export async function generateStaticParams() {
  const slugs = await client.fetch(
    groq`*[_type == "blog" && defined(slug.current)]{ "slug": slug.current }`
  );
  return slugs.map((s: { slug: string }) => ({ slug: s.slug }));
}

Step 4 — Rendering MDX Content

Blog post content in Sanity is stored as an MDX string. To render it, I use next-mdx-remote/rsc — which compiles MDX entirely on the server inside a React Server Component. No client-side JS, no hydration overhead.

import { compileMDX } from "next-mdx-remote/rsc";
import remarkGfm from "remark-gfm";
import rehypeSlug from "rehype-slug";
import rehypeAutolinkHeadings from "rehype-autolink-headings";
import rehypeHighlight from "rehype-highlight";

export async function parseMDX(source: string, components = {}) {
  const { content } = await compileMDX({
    source,
    components,
    options: {
      parseFrontmatter: true,
      mdxOptions: {
        remarkPlugins: [remarkGfm],
        rehypePlugins: [rehypeSlug, rehypeAutolinkHeadings, rehypeHighlight],
      },
    },
  });
  return content;
}

Here's what each rehype plugin does:

Step 5 — Table of Contents

Since rehypeSlug adds IDs to all headings, I built a sidebar TOC. The heading extraction runs server-side on the raw MDX string — before compilation:

export function extractHeadings(mdx: string) {
  const headingRegex = /^(#{1,4})\s+(.*)$/gm;
  const headings: { level: number; text: string; id: string }[] = [];

  let match;
  while ((match = headingRegex.exec(mdx)) !== null) {
    const level = match[1].length;
    const cleanText = match[2].replace(/[*_`~\[\]]/g, "");
    const id = slugify(cleanText);
    headings.push({ level, text: cleanText, id });
  }

  return headings;
}

The key detail: extractHeadings runs on the raw MDX string, not the compiled HTML. It strips markdown formatting characters and produces slugified IDs that exactly match what rehypeSlug generates in the rendered HTML. Press Ctrl + F in your browser — you'll see heading IDs appear in the URL bar when you click any TOC link.

Step 6 — ISR and Caching

Blog listing page ISR

export const revalidate = 60;

Individual blog pages SSG

Pre-built at deploy time via generateStaticParams. New posts added after a deploy use Next.js's on-demand fallback — the first visitor triggers a build, subsequent visitors get the cached page instantly.

Step 7 — SEO and JSON-LD

Each blog post gets a full JSON-LD structured data block injected into the page. This is what Google uses to understand your content beyond reading the page text.

const jsonLd = {
  "@context": "https://schema.org",
  "@type": "Article",
  headline: post.title,
  description: post.shortDescription,
  author: {
    "@type": "Person",
    name: "Dhiraj Bhawsar",
    url: "https://dhirajbhawsar.in",
  },
  datePublished: post.publishedAt,
  dateModified: post._updatedAt || post.publishedAt,
};

The Diagram Edge Case

There's one tricky bug worth calling out. Sanity content sometimes contains ASCII diagram text that the MDX parser misreads as JSX because of arrow-style syntax. The parseMDX.ts file handles this with a pre-processing regex that wraps Diagram content in code blocks before compilation runs.

Here's what a rendered Diagram looks like:

Request → Next.js Server
    ↓
generateStaticParams (build time)
    ↓
client.fetch(singleBlogQuery)
    ↓
parseMDX(post.content, mdxComponents)
    ↓
Rendered React Component → Browser

Other Things Worth Knowing

Local fonts — no Google Fonts requests

Instead of loading fonts from Google (which adds a network round-trip on every load), I serve fonts locally using Next.js localFont with display: swap. Text renders immediately in a system font, then swaps — no layout shift, no invisible content.

Production console cleanup Next.js

compiler: {
  removeConsole: process.env.NODE_ENV === "production",
},

WWW redirect SEO

A permanent redirect from www.dhirajbhawsar.in to dhirajbhawsar.in is handled directly in next.config.ts. No duplicate content penalty from Google for having two versions of the same URL.

What I Actually Learned

I want to be honest here — most "what I learned" sections are just disguised tips lists. Here's what actually caught me off guard.

Useful Resources

If you're more of a visual learner, this is one of the best walkthroughs of the Next.js App Router + Sanity stack on YouTube:

Is This Stack Worth It?

Thanks for reading. If you have questions, find me on Instagram at @dhirajtsx or visit dhirajbhawsar.in.