I’ve been really into Fumadocs lately. The feature set is already solid out of the box, but I went ahead and customized a few things to make it more convenient. Hopefully some of this is useful if you’re looking to improve your own setup.

Customizing Fumadocs: A Few New Features I Added

A YouTube Embed Component

The <YouTubeEmbed> component lets you embed YouTube videos safely.

mdx
<YouTubeEmbed videoId="LX6A3OmY4uk" title="Video Title" />

This component has a few nice properties:

  • Responsive (keeps a 16:9 aspect ratio)
  • Sets the right security attributes automatically
  • Performance-optimized (lazy loading)

A UI Path Display Component

The <UiPath> component lets you visually show a sequence of UI steps.

mdx
<UiPath>Email activity > Has a hard bounced delivery > Yes</UiPath>

This component has a few nice properties:

  • Automatically parses a path separated by >
  • Renders each step as a chip
  • Highlights the final step with an “active” style (blue background)
  • Separates steps with an arrow (›)

The styling is defined in app/globals.css, using the following classes:

  • .ui-chip: the default chip style (gray background)
  • .ui-chip.is-active: the active chip style (blue background)
  • .ui-sep: styling for the separator character (›)

Article Date Display and Outdated-Article Warnings

If you set created and updated in an MDX file’s frontmatter, the article page automatically shows the creation and last-updated dates.

mdx
---
title: Article Title
created: 2021-04-18
updated: 2024-02-28
---
  • created: the article’s creation date
  • updated: the article’s last-updated date (not shown if it’s the same as the creation date)

Also, any article that hasn’t been updated in over a year automatically shows the following warning:

This article hasn’t been updated in over a year. The info here might be out of date…

This is implemented in components/article-dates.tsx, and it renders directly below the article title.

The <RelatedArticles> component lets you show related articles inside a post.

mdx
<RelatedArticles related="blog-japanese,css,embed-html" />

Features:

  • Specify file-name slugs (e.g. blog-japanese), comma-separated
  • Works with both parenthesized folders ((pagecreate)/blog-japanese.mdx) and regular folders (payment/cant-free-trial.mdx)
  • Shows each article’s title and a category badge
  • A code-block-style card design with a white background
  • A Zap icon next to the heading, and a NotebookText icon next to each article
  • No underline on links, with a color change on hover

Example usage:

mdx
---
title: Creating a Blog Post
---

## Body

Here are some related articles.

<RelatedArticles related="blog-japanese,css,embed-html" />

It also works fine with spaces around the commas:

mdx
<RelatedArticles related="blog-japanese, css, embed-html" />

Implementation files:

  • components/related-articles.tsx: the related-articles display component
  • lib/getPageBySlug.ts: a helper function for fetching a page from its slug
    • getPageBySlug(slug): fetches a single page from a slug
    • getPagesBySlugs(slugs): fetches multiple pages from a list of slugs
    • getCategoryTitleFromPage(page): gets a category title from a page

Technical details:

  • Caches the slug-to-page map to optimize performance
  • Automatically determines the category from the file path (including parenthesized folders)
  • Category info is pulled from meta.json or index.mdx, using an in-memory cache

Homepage Features

The homepage (content/docs/index.mdx) has the following features implemented.

Recently Added and Recently Updated Articles

Shows articles that have created or updated set in their frontmatter, sorted by date.

mdx
import { RecentCreatedPosts, RecentUpdatedPosts } from '@/components/recent-posts';

## Recently Added Articles

<RecentCreatedPosts limit={10} />

## Recently Updated Articles

<RecentUpdatedPosts limit={10} />

Features:

  • Each article is displayed as a card, with a hover effect
  • A FileText icon appears before each article title
  • Category badges are shown (e.g. Billing, Products/Lessons)
  • Dates aren’t shown — it’s a simple list format

Implementation files:

  • components/recent-posts.tsx: the article-list display component
  • lib/recent-posts.ts: the article-fetching functions (getRecentCreatedPosts, getRecentUpdatedPosts)

Featured Topics & Articles (Category-Based Display)

A shortcode component that shows up to 5 articles per category.

mdx
import { CategoryPosts } from '@/components/category-posts';

## Featured Topics & Articles

<CategoryPosts category="payment" limit={5} />

<CategoryPosts category="product" limit={5} />

<CategoryPosts category="students" limit={5} />

Features:

  • Category names are shown as links, and clicking one navigates to the category page
  • A BookText icon appears before each article
  • Articles are sorted by most-recently-updated (or creation date, if there’s no update date)
  • You can reorder the sections by changing the order of <CategoryPosts /> calls in the MDX file

A shared footer is shown across the whole site. It’s implemented in components/footer.tsx.

Layout:

  • A responsive two-column design (side-by-side on large screens, stacked on mobile)
  • Left column: site logo, description, social media icons, and logged-in user info
  • Right column: site notices (terms of service, update info, etc.)

What’s in the left column:

  • Site title (links to /docs)
  • Site description
  • Social media icons (GitHub, Discord, YouTube, Twitter/X)
  • Logged-in user info (placeholder)
    • “Logged in” status
    • Username display
    • Log out / change password buttons

What’s in the right column:

  • Site description and notices
  • A note about how information gets updated
  • A note about how new articles get added

Implementation files:

  • components/footer.tsx: the footer component
  • app/layout.tsx: adds the footer to the root layout

The footer is shown automatically on every page, and it’s styled using Fumadocs’ theme variables.