DEV Community: Rajiv Seelam

Setup a Blog with NextJS & Fuma Docs

Rajiv Seelam — Wed, 23 Apr 2025 09:30:40 +0000

What features would you want on your blog? Here are the ones I chose:

Features

[x] Static site that can be published to GitHub Pages
[x] MDX support: I work on frontend code, so I need to embed React components in my posts
[x] Search
[x] Table of contents (Clerk style)
[x] A Blog Post
[x] List of Posts with Pagination
[x] Categories
[x] Series
[x] Metadata with Social Images
[x] Static (yes, repeating for emphasis)

Setup

The official FumaDocs documentation has an article on setting up a blog: Setup a Blog. Using that as a foundation, I built my blog with the features above.

You can proceed in two ways:

Clone the current repo
Follow the steps below to add these features to your existing Next.js site

Install and Configure Fuma Docs

Install Fuma Docs

You need a working Fuma Docs setup. If you don't have one, create it using the following command:

pnpm create fumadocs-app

Or you can configure FumaDocs manually.

At this point, you should have a basic setup ready with the files: source.config.ts and lib/source.ts.

Setup ShadCN Components

If you already have shadcn set up, you don't need to run the following command.

pnpm dlx shadcn@latest init

We need the following components:

button
popover
badge
card

You can add all of the above with:

pnpm dlx shadcn@latest add button popover badge card

We also need a book icon component, which is used when displaying series:

pnpm dlx shadcn@latest add "https://21st.dev/r/designali-in/book"

Define a Collection for Blog

Install zod as we will use it to add a frontmatter schema.

zod

Now define a collection for the blog. Add the following:

import {
  defineDocs,
  defineConfig,
  defineCollections,
  frontmatterSchema,
} from "fumadocs-mdx/config";
import { z } from "zod";

export const blog = defineCollections({
  type: "doc",
  dir: "content/blog",
  schema: frontmatterSchema.extend({
    author: z.string(),
    date: z
      .string()
      .or(z.date())
      .transform((value, context) => {
        try {
          return new Date(value);
        } catch {
          context.addIssue({
            code: z.ZodIssueCode.custom,
            message: "Invalid date",
          });
          return z.NEVER;
        }
      }),
    tags: z.array(z.string()).optional(),
    image: z.string().optional(),
    draft: z.boolean().optional().default(false),
    series: z.string().optional(),
    seriesPart: z.number().optional(),
  }),
});

Add the following to lib/source.ts:

import { docs, blog } from "@/.source";
import { loader } from "fumadocs-core/source";
import { createMDXSource } from "fumadocs-mdx";

export const blogSource = loader({
  baseUrl: "/blog",
  source: createMDXSource(blog),
});

export const {
  getPage: getBlogPost,
  getPages: getBlogPosts,
  pageTree: pageBlogTree,
} = blogSource;

export type BlogPost = ReturnType<typeof getBlogPost>;

Add fumadocs-blog components

There are multiple features, so instead of adding files one by one, we'll copy entire folders using the giget command.

Add all the required components

npx giget gh:rjvim/rjvim.github.io/packages/fumadocs-blog/src fumadocs-blog --force

Add /blog route page

npx giget gh:rjvim/rjvim.github.io/apps/web/app/\(home\)/blog app/\(home\)/blog --force

Add /blog-og route page

npx giget gh:rjvim/rjvim.github.io/apps/web/app/blog-og app/blog-og --force

Correct the imports

The original components are built to work with a monorepo, so we need to correct the imports.

Run the following commands:

sed -i '' 's|@repo/fumadocs-blog/blog|@/fumadocs-blog|g' 'app/(home)/blog/[[...slug]]/page.tsx'

sed -i '' 's|@repo/fumadocs-blog/blog|@/fumadocs-blog|g' 'app/blog-og/[[...slug]]/route.tsx'

Add styles to global.css

```css title="global.css"
@import "../fumadocs-blog/styles/globals.css";





### Configure the blog

If fumadocs-blog was an npm package, all the above steps would be handled by that. Now, we need to configure the blog. Blog configuration drives following:

- Metadata
- Components
- Categories
- Series
- Others

_I will document a detailed guide, but as of now the following should give majority of the idea_

Add the following file "blog-configuration.tsx" in your repo at root path, we import this using `@/blog-configuration`.



```tsx
import type { Metadata } from "next/types";
import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from "@/components/ui/popover";
import { Badge } from "@/components/ui/badge";
import { Book } from "@/components/ui/book";
import { Card } from "@/components/ui/card";
import type { BlogConstants, BlogConfiguration } from "@/fumadocs-blog";
import { PostCard } from "@/fumadocs-blog";
import {
  Brain,
  Book as LucideBook,
  Code,
  Cog,
  Lightbulb,
  Megaphone,
  Rocket,
  Users,
  Wrench,
  BookIcon,
} from "lucide-react";

// Blog text constants that can be customized

export const blogConstants: BlogConstants = {
  // General
  blogTitle: "Blog",
  blogDescription: "Articles and thoughts",
  siteName: "myblog.com",
  defaultAuthorName: "My Name",
  xUsername: "@my_x_username",
  // Pagination
  paginationTitle: (page: number) => `Blog - Page ${page}`,
  paginationDescription: (page: number) =>
    `Articles and thoughts - Page ${page}`,
  categoryPaginationTitle: (category: string, page: number) =>
    `${category.charAt(0).toUpperCase() + category.slice(1)} - Page ${page}`,
  categoryPaginationDescription: (category: string, page: number) =>
    `Articles in the ${category} category - Page ${page}`,
  // URLs
  blogBase: "/blog",
  blogOgImageBase: "blog-og",
  pageSize: 5,
};

export function createBlogMetadata(
  override: Metadata,
  blogConstants: BlogConstants
): Metadata {
  // Derive values from the core properties
  const siteUrl = `https://${blogConstants.siteName}`;
  const author = {
    name: blogConstants.defaultAuthorName,
    url: siteUrl,
  };
  const creator = blogConstants.defaultAuthorName;

  return {
    ...override,
    authors: [author],
    creator: creator,
    openGraph: {
      title: override.title ?? undefined,
      description: override.description ?? undefined,
      url: siteUrl,
      siteName: blogConstants.siteName,
      ...override.openGraph,
    },
    twitter: {
      card: "summary_large_image",
      site: blogConstants.xUsername,
      creator: blogConstants.xUsername,
      title: override.title ?? undefined,
      description: override.description ?? undefined,
      ...override.twitter,
    },
    alternates: {
      canonical: "/",
      types: {
        "application/rss+xml": "/api/rss.xml",
      },
      ...override.alternates,
    },
  };
}

export function getBlogConfiguration(): BlogConfiguration {
  return {
    PostCard: PostCard,
    Button,
    Popover,
    PopoverContent,
    PopoverTrigger,
    Badge,
    Book,
    Card,
    cn,
    config: {
      blogBase: blogConstants.blogBase,
      blogOgImageBase: blogConstants.blogOgImageBase,
      pageSize: 5,
    },
  };
}

export const useBlogConfiguration = getBlogConfiguration;

// Moved from lib/categories.ts
export const getCategoryBySlug = (slug: string) => {
  const categories = {
    idea: {
      label: "Idea",
      icon: Brain,
      description:
        "Exploratory thoughts and wild concepts for Teurons and beyond.",
    },
    opinions: {
      label: "Opinions",
      icon: Megaphone,
      description:
        "Subjective, wild, gut-hunch takes—less informed, out-of-box rants.",
    },
  };

  return (
    categories[slug as keyof typeof categories] || {
      label: slug.toString().replace(/-/g, " ").toLowerCase(),
      icon: BookIcon,
    }
  );
};

export const getSeriesBySlug = (slug: string) => {
  const series = {
    x: {
      label: "Series X",
      icon: LucideBook,
      description: "A Sample Series",
    },
    // Add more series here as needed
  };

  return (
    series[slug as keyof typeof series] || {
      label: slug.charAt(0).toUpperCase() + slug.slice(1),
      icon: LucideBook,
      description: `Articles in the ${
        slug.charAt(0).toUpperCase() + slug.slice(1)
      } series.`,
    }
  );
};

Add following sample post

Add the sample .mdx file below to test if everything is working. Place it at content/blog/idea/zero-trust-security.mdx.

A few things to note: "idea" is the category of the blog, and "zero-trust-security" will be the URL of the blog post.

---
title: "Zero Trust Security"
description: "Why modern security architectures assume breach and verify everything"
author: lina
date: 2025-03-22
tags: [security, zero trust, cybersecurity, enterprise]
image: https://shadcnblocks.com/images/block/placeholder-5.svg
---

# Zero Trust Security

Traditional security models operated on the principle of "trust but verify" and focused on perimeter defense. Zero Trust flips this paradigm with a simple principle: never trust, always verify.

## Core Principles

Zero Trust is built on several foundational ideas:

### Assume Breach

Zero Trust architectures operate under the assumption that attackers are already present within the network.

### Verify Explicitly

Every access request must be fully authenticated, authorized, and encrypted:

1. Strong identity verification for all users
2. Device health validation
3. Just-in-time and just-enough access
4. Context-aware policies

## Implementation Strategies

Moving to Zero Trust requires systematic changes:

### Identity as the Control Plane

Modern security centers on identity rather than network location:

### Micro-Segmentation

Network security shifts from perimeter-based to fine-grained segmentation between workloads.

Test the blog

If you open http://localhost:3000/blog, you'll see a list of posts—at this point, only one. You can add more, edit the content, and try it out. The pagination size is 5, so after 5 posts you'll see a paginator.

You can open a blog detail page and see details like tags, series, categories, etc.

If you want a post to be part of a series, add the following frontmatter to the .mdx file:

series: building-react-component-library
seriesPart: 1

Future

This development is driven by my needs and the products I'm working on. Here are a few things in the pipeline:

Newsletter subscription (But how do you do it for a static site?)
Tags
Make other components overridable so you can style them better
Make this a clonable template
The biggest problem I have with templates is that once you clone and start changing them, updating is not easy. You're off-track from the first second. So, I'm leaning towards a monorepo where I can balance open code and updates like a package.

Anything else? Hit me up on Twitter and follow for more updates.

Embedding X Posts in Fumadocs

Rajiv Seelam — Thu, 17 Apr 2025 06:23:13 +0000

This tutorial will guide you through the process of embedding X (formerly Twitter) posts in your Fumadocs site. We'll cover installation, component setup, and usage in MDX files.

Step 1: Install the Required Package

First, you need to install the react-social-media-embed package:

pnpm install react-social-media-embed

Step 2: Create the XEmbedClient Component

Create a client component wrapper for the XEmbed component. This needs to be a client component because it interacts with the X embed script.

"use client";

import { XEmbed, XEmbedProps } from "react-social-media-embed";

export function XEmbedClient({ ...props }: XEmbedProps) {
  return (
    <div className="flex justify-center">
      <XEmbed {...props} />
    </div>
  );
}

The client component wrapper:

Uses the "use client" directive to ensure it runs on the client side
Wraps the XEmbed component from react-social-media-embed
Adds a flex container with center alignment for better display
Maintains the same API as the original XEmbed component

Step 3: Add the Component to MDX Components

Update your mdx-components.tsx file to include the XEmbedClient component:

import defaultMdxComponents from "fumadocs-ui/mdx";
import type { MDXComponents } from "mdx/types";
import { XEmbedClient } from "./components/XEmbedClient";

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    XEmbed: XEmbedClient,
    ...components,
  };
}

Step 4: Use the XEmbed Component in Your MDX Files

Now you can use the XEmbed component in your MDX files:

<XEmbed url="https://x.com/rjv_im/status/1912033485285376492" width={325} />

Example

Here's an example of an embedded X post: https://rjv.im/blog/solution/embed-x-post-in-fuma-docs

Documentation

You can also embed Facebook, LinkedIn etc., too. Refer to react-social-media-embed for more details.

FumaDocs React Component to Display Code from Github Repos

Rajiv Seelam — Thu, 17 Apr 2025 06:17:53 +0000

The GithubCodeBlock component allows you to embed and display code from GitHub repositories directly in your Fuma Docs application. It supports line extraction, syntax highlighting, and line highlighting features.

Installation

You need to have fumadocs setup ready and running

Step 1: Copy following code anywhere into your components

import * as Base from "fumadocs-ui/components/codeblock";
import { highlight } from "fumadocs-core/highlight";
import { transformerMetaHighlight } from "@shikijs/transformers";

// Types
export interface CodeBlockProps {
  code: string;
  wrapper?: Base.CodeBlockProps;
  lang: string;
  highlightLines?: string;
}

interface GithubCodeBlockProps {
  url: string;
  extractLines?: boolean;
  highlightLines?: string;
  wrapper?: Base.CodeBlockProps;
}

interface GitHubReference {
  rawUrl: string;
  fromLine?: number;
  toLine?: number;
  highlightLines?: string;
}

// Helper functions
function formatHighlightLines(highlightLines?: string): string | undefined {
  if (!highlightLines) return undefined;
  return highlightLines.startsWith("{") && highlightLines.endsWith("}")
    ? highlightLines
    : `{${highlightLines}}`;
}

function getLanguageFromUrl(url: string): string {
  try {
    return url.split(".").pop()?.toLowerCase() || "";
  } catch {
    return "";
  }
}

function parseGitHubUrl(url: string): GitHubReference {
  try {
    // Split the URL to separate the line reference part
    const [githubUrl, loc] = url.split("#");

    if (!githubUrl) {
      throw new Error("Invalid GitHub URL");
    }

    // Initialize line reference variables
    let fromLine: number | undefined;
    let toLine: number | undefined;
    let highlightLines: string | undefined;

    // Parse line references if present
    if (loc) {
      const lineParts = loc.split("-");

      if (lineParts[0]?.startsWith("L")) {
        fromLine = parseInt(lineParts[0].slice(1), 10) - 1;

        if (lineParts[1]?.startsWith("L")) {
          toLine = parseInt(lineParts[1].slice(1), 10) - 1;
        } else {
          toLine = fromLine;
        }

        // Always generate highlight lines from location
        // These will be used if no explicit highlightLines prop is provided
        if (fromLine !== undefined && toLine !== undefined) {
          const startLine = fromLine + 1;
          const endLine = toLine + 1;
          highlightLines =
            startLine === endLine
              ? `{${startLine}}`
              : `{${startLine}-${endLine}}`;
        }
      }
    }

    // Parse GitHub URL to create raw URL
    const urlObj = new URL(githubUrl);
    const pathParts = urlObj.pathname.split("/").slice(1);

    if (pathParts.length < 5) {
      throw new Error("Invalid GitHub repository path");
    }

    const [org, repo, _, branch, ...pathSeg] = pathParts;

    if (!org || !repo || !branch || pathSeg.length === 0) {
      throw new Error("Missing required GitHub path components");
    }

    // Create reference object with raw URL and line info
    return {
      rawUrl: `https://raw.githubusercontent.com/${org}/${repo}/${branch}/${pathSeg.join("/")}`,
      fromLine,
      toLine,
      highlightLines,
    };
  } catch (error) {
    console.error("Error parsing GitHub URL:", error);
    throw new Error(
      `Invalid GitHub URL: ${error instanceof Error ? error.message : String(error)}`
    );
  }
}

async function fetchCode(url: string, fromLine?: number, toLine?: number) {
  try {
    const response = await fetch(url, { cache: "force-cache" });

    if (!response.ok) {
      throw new Error(
        `Failed to fetch code: ${response.status} ${response.statusText}`
      );
    }

    const content = await response.text();

    // Return full content if no line numbers are specified
    if (fromLine === undefined || toLine === undefined) {
      return content;
    }

    // Extract specific lines
    const lines = content.split("\n");
    const selectedLines = lines.slice(fromLine, toLine + 1);

    if (selectedLines.length === 0) {
      return content;
    }

    // Calculate common indentation to remove
    const commonIndent = selectedLines.reduce(
      (indent: number, line: string) => {
        if (line.length === 0) return indent;
        const spaces = line.match(/^\s+/);
        return spaces ? Math.min(indent, spaces[0].length) : 0;
      },
      Infinity
    );

    // Remove common indentation and join lines
    return selectedLines
      .map((line) => {
        if (line.length === 0) return line;
        return line.slice(commonIndent < Infinity ? commonIndent : 0);
      })
      .join("\n");
  } catch (error) {
    console.error("Error fetching code:", error);
    return `// Error fetching code: ${error instanceof Error ? error.message : String(error)}`;
  }
}

// Components
export async function CodeBlock({
  code,
  lang,
  wrapper,
  highlightLines,
}: CodeBlockProps) {
  const rendered = await highlight(code, {
    lang,
    meta: highlightLines ? { __raw: highlightLines } : undefined,
    themes: {
      light: "github-light",
      dark: "github-dark",
    },
    components: {
      pre: Base.Pre,
    },
    transformers: [transformerMetaHighlight()],
  });

  return <Base.CodeBlock {...wrapper}>{rendered}</Base.CodeBlock>;
}

export default async function GithubCodeBlock({
  url,
  extractLines = false,
  highlightLines,
  wrapper,
}: GithubCodeBlockProps) {
  try {
    // Validate GitHub URL
    if (!url.includes("github.com")) {
      throw new Error("This component only supports GitHub URLs");
    }

    // Parse GitHub URL to get raw URL and line info
    const reference = parseGitHubUrl(url);

    // Format highlight lines for Shiki
    // Priority: explicitly provided highlightLines prop > lines from URL loc
    const formattedHighlightLines = formatHighlightLines(
      highlightLines || reference.highlightLines
    );

    // Fetch the code content, extracting specific lines if needed
    const code = await fetchCode(
      reference.rawUrl,
      extractLines ? reference.fromLine : undefined,
      extractLines ? reference.toLine : undefined
    );

    const lang = getLanguageFromUrl(reference.rawUrl);

    return (
      <CodeBlock
        lang={lang}
        code={code}
        highlightLines={formattedHighlightLines}
        wrapper={wrapper}
      />
    );
  } catch (error) {
    console.error("Error in GithubCodeBlock:", error);
    return (
      <CodeBlock
        lang="text"
        code={`// Error: ${error instanceof Error ? error.message : String(error)}`}
        wrapper={wrapper}
      />
    );
  }
}

Step 2: Add to MDX Components

import defaultMdxComponents from "fumadocs-ui/mdx";
import type { MDXComponents } from "mdx/types";
import GithubCodeBlock from "./components/github-code-block";

export function getMDXComponents(components?: MDXComponents): MDXComponents {
  return {
    ...defaultMdxComponents,
    GithubCodeBlock: GithubCodeBlock,
    ...components,
  };
}

Basic Usage

<GithubCodeBlock url="https://github.com/rjvim/react-component-library-starter/blob/main/lerna.json" />

Props

The component accepts the following props:

Prop	Type	Default	Description
`url`	`string`	(required)	GitHub URL to the file you want to display
`extractLines`	`boolean`	`false`	Whether to extract specific lines from the file
`highlightLines`	`string`	`undefined`	Lines to highlight in the format `"{1,3-4}"`
`wrapper`	`object`	`undefined`	CodeBlockProps to pass to the underlying CodeBlock component

Examples

Display a Complete File

<GithubCodeBlock url="https://github.com/rjvim/react-component-library-starter/blob/main/lerna.json" />

Extract Specific Lines

You can extract specific lines from a file by adding a line reference to the URL and setting extractLines to true:

<GithubCodeBlock
  url="https://github.com/rjvim/react-component-library-starter/blob/main/lerna.json#L2-L4"
  extractLines={true}
/>

Highlight Specific Lines

You can highlight specific lines using the highlightLines prop:

<GithubCodeBlock
  url="https://github.com/rjvim/react-component-library-starter/blob/main/lerna.json"
  highlightLines="{2,4}"
/>

Launch Post

// Detect dark theme var iframe = document.getElementById('tweet-1912033485285376492-162'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1912033485285376492&theme=dark" }

Note: In dev.to to editor I am not able to show the output of using the component, you can check that on: https://rjv.im/blog/solution/github-code-block