Docusaurus v2 - recent blogs list for homepage

3 min read 06-10-2024

Docusaurus v2 - recent blogs list for homepage

Displaying Recent Blog Posts on Your Docusaurus v2 Homepage

Docusaurus v2 is a fantastic tool for building static websites, particularly for documentation and blogs. Often, you want to showcase recent blog posts on your homepage to keep visitors engaged and informed. This article guides you through integrating a recent blog post list into your Docusaurus v2 site, enhancing its appeal and user experience.

The Problem:

Let's say you have a Docusaurus v2 site with a blog section and you want to display the three most recent posts prominently on your homepage.

The Solution:

Docusaurus v2 provides flexibility in customizing your site's structure and content. You can achieve this by:

Utilizing the @docusaurus/plugin-content-blog plugin: This plugin is designed to manage your blog posts and integrate them seamlessly into your Docusaurus site.
Leveraging the Homepage_Features component: This component is a standard part of Docusaurus, offering a structured layout for displaying content on your homepage.

Implementing the Solution:

Let's break down the implementation process step-by-step:

Ensure the @docusaurus/plugin-content-blog plugin is installed: This is usually done during the initial setup of your Docusaurus site. If not, install it by adding the following to your package.json and running npm install:

"dependencies": {
  ...
  "@docusaurus/plugin-content-blog": "^2.0.0-beta.0",
  ...
}

Modify your docusaurus.config.js file:

Ensure the blog plugin is enabled:

module.exports = {
  title: 'My Docusaurus Site',
  tagline: 'Dinosaurs are cool',
  url: 'https://your-site.com',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/favicon.ico',
  organizationName: 'facebook', // Usually your GitHub org/user name.
  projectName: 'docusaurus', // Usually your repo name.
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        routeBasePath: '/blog',
        postsPerPage: 10,
        showReadingTime: true,
        editUrl:
          'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
        readingTime: ({ content }) =>
          readingTime(content, { wordsPerMinute: 300 }),
      },
    ],
    // Other plugins ...
  ],
  themeConfig: {
    ...
  },
};

In your themeConfig, customize the Homepage_Features component to display recent blog posts:

themeConfig: {
    ...
    // ... other themeConfig settings ...
    homepage: {
      features: [
        {
          title: 'Recent Blog Posts',
          items: [
            {
              title: 'Display Recent Posts',
              content:
                'Use the `@docusaurus/plugin-content-blog` and customize `Homepage_Features` to display recent blog posts on your Docusaurus site.',
            },
          ],
        },
      ],
    },
  },

Implement the logic for retrieving recent blog posts: You can achieve this using the useBlogPosts hook provided by the @docusaurus/plugin-content-blog plugin. Here's an example:

import React from 'react';
import { useBlogPosts } from '@docusaurus/plugin-content-blog';

const RecentBlogPosts = () => {
  const { posts } = useBlogPosts({
    limit: 3, // Display the 3 most recent posts
  });

  return (
    <div>
      <h2>Recent Posts</h2>
      <ul>
        {posts.map((post) => (
          <li key={post.id}>
            <a href={post.permalink}>{post.title}</a>
            <p>{post.description}</p>
          </li>
        ))}
      </ul>
    </div>
  );
};

export default RecentBlogPosts;

Integrate RecentBlogPosts component into your homepage:

Import the component into your Homepage.js file.
Include the component within the Homepage_Features section in your homepage.

import React from 'react';
import clsx from 'clsx';
import styles from './styles.module.css';
import RecentBlogPosts from './RecentBlogPosts'; // Import your component

// ... other imports ... 

function Homepage() {
  return (
    <header className={clsx('hero hero--primary', styles.heroBanner)}>
      <div className="container">
        <h1 className="hero__title">My Docusaurus Site</h1>
        <p className="hero__subtitle">Dinosaurs are cool</p>
        <div className={styles.buttons}>
          <a
            className="button button--secondary button--lg"
            href="/docs/intro"
          >
            Docusaurus Docs
          </a>
        </div>
      </div>
    </header>
    <main>
      <Homepage_Features>
        <RecentBlogPosts /> {/* Include the recent blog posts component */}
      </Homepage_Features>
    </main>
  );
}

export default Homepage;

Customization & Optimization:

Customize Styling: Use CSS to style the list, links, and content of your recent blog posts. Refer to the Docusaurus documentation for styling options.
Adjust Limit: Modify the limit value in the useBlogPosts hook to display a different number of posts.
Filter by Category: If you categorize your blog posts, you can filter recent posts based on a specific category.
Pagination: Implement pagination for large blog archives to improve navigation and user experience.

Additional Notes:

This implementation assumes you have the @docusaurus/plugin-content-blog plugin enabled and configured.
If you have a custom Homepage_Features component, adapt the integration accordingly.
The readingTime function in the example is not essential for displaying posts but can be used to show approximate reading time.
Remember to restart your Docusaurus development server after making changes to see your updates reflected.

Conclusion:

Displaying recent blog posts on your Docusaurus v2 homepage is a simple yet effective way to engage visitors and encourage further exploration of your content. By leveraging the built-in features of Docusaurus and the blog plugin, you can easily customize your homepage to showcase the most relevant information and drive user engagement.