Skip to Content

Blog

Add a blog with post, index and tag pages.

Turn a content source into a blog. Each post gets a page, like /blog/hello-world, with an index at /blog and tag pages at /blog/tags.

Setup

Install

npm i @fumapress/blog

Add the Styles

Add this after the imports in your stylesheet:

src/app.css
@import "@fumapress/blog/css/preset.css";

Create the Source

Create a source for your posts and pass its key to the plugin:

press.config.tsx
import { createPress } from "fumapress";
import { defineDocs } from "fumadocs-mdx/macro";
import { blogPlugin } from "@fumapress/blog";
import { blogPageSchema } from "@fumapress/blog/schema";

const docs = defineDocs({ dir: "content/docs" });

const blog = defineDocs({
  dir: "content/blog",
  docs: { schema: blogPageSchema },
});

export default createPress({
  docs: docs.toFumadocsSource(),
  blog: blog.toFumadocsSource({ baseDir: "blog" }),
})
  .plugins(blogPlugin({ source: "blog" }));

With baseDir: "blog", the posts show as a blog folder in the docs sidebar. To hide it, exclude the folder in the root meta.json of your docs:

content/docs/meta.json
{
  "pages": ["...", "!blog"]
}

Writing Posts

content/blog/hello-world.mdx
---
title: My Blog Post
description: Hello World!!!
date: 2026-09-06
tags: [my-tag]
authors: [fuma]
image: /covers/hello.png
---

## Introduction

Welcome to my first blog post.

Posts are ordered by date. Each tag gets a page, and image shows on post cards.

Authors

The keys of authors are the IDs in the frontmatter. An ID that isn't registered shows as the plain ID.

press.config.tsx
blogPlugin({
  source: "blog",
  authors: {
    fuma: {
      name: "Fuma Nama",
      title: "Maintainer",
      url: "https://fuma-nama.dev",
      image: "https://github.com/fuma-nama.png",
    },
  },
});

Prop

Type

Customization

Other Content Sources

Posts can come from any content source, like Notion. The date comes from the getPageCreatedAt hook of its plugin. These options read the other fields when they aren't in the frontmatter:

press.config.tsx
blogPlugin({
  source: "blog",
  getTags: (page) => page.data.tags,
  getAuthors: (page) => page.data.authors,
  getImage: (page) => page.data.image,
});

To use multiple sources as posts, pass their keys:

press.config.tsx
blogPlugin({
  source: ["blog", "news"],
  getTags: (page) => page.data.tags ?? [page.type],
});

URLs

Set a path to move a page, or false to remove it:

press.config.tsx
blogPlugin({
  source: "blog",
  paths: {
    index: "/news",
    tags: false,
  },
});

Custom UI

In renderPage, a post has the type of its source key, like blog. The other pages are blog.index, blog.tags and blog.tag. This example replaces the index, and renders the built-in post in another layout:

press.config.tsx
import { BlogPostView } from "@fumapress/blog";
import { HomeLayout } from "fumadocs-ui/layouts/home";

renderPage(props) {
  const { renderDefault } = props;
  // the Home Layout takes these props, the others are for docs layouts
  const { nav, links, githubUrl, i18n, themeSwitch, searchToggle } = props.layoutProps;
  const home = { nav, links, githubUrl, i18n, themeSwitch, searchToggle };
  switch (props.type) {
    case "blog.index":
      return (
        <HomeLayout {...home}>
          <ul>
            {props.posts.map((post) => (
              <li key={post.page.url}>{post.page.data.title}</li>
            ))}
          </ul>
        </HomeLayout>
      );
    case "blog":
      return (
        <HomeLayout {...home}>
          <BlogPostView post={props.post} newer={props.newer} older={props.older}>
            {props.body}
          </BlogPostView>
        </HomeLayout>
      );
    default:
      return renderDefault();
  }
},

@fumapress/blog also exports BlogIndexView, BlogTagsView and BlogTagView.

Remote Images

An optimizer rejects hosts you don't allow, including for covers and avatars. List the provider with the allowed hosts, and set image: false in recommendedPreset():

press.config.tsx
import { selfHostedImage } from "fumapress/plugins/image/self-hosted";

selfHostedImage({ allowedHosts: ["avatars.githubusercontent.com"] });

Watch for redirects

A redirect to another origin is checked again, so allow the final host too. An avatar at github.com, for example, redirects to avatars.githubusercontent.com.

Listing Posts

getBlogPosts() returns all posts, newest first:

src/pages/index.tsx
import { getPressContext } from "fumapress";
import { Link } from "fumapress/client";
import { getBlogPosts } from "@fumapress/blog";
import type { app } from "../../press.config";

export default async function Home() {
  const posts = await getBlogPosts(getPressContext<typeof app>());

  return (
    <ul>
      {posts.slice(0, 3).map((post) => (
        <li key={post.page.url}>
          <Link href={post.page.url}>{post.page.data.title}</Link>
          {post.authors.map((author) => author.name).join(", ")}
        </li>
      ))}
    </ul>
  );
}

With internationalization, pass the language: getBlogPosts(ctx, { lang }).

Options

Prop

Type

Last updated on

On this page