# Display Docusaurus Blog Posts as Cards - A Step-by-Step Guide > Learn how to visually showcase your Docusaurus blog posts using customizable card layouts. --- ![Display Docusaurus Blog Posts as Cards - A Step-by-Step Guide](/img/v2/docusaurus_react.webp) **TL;DR** This comprehensive guide demonstrates how to transform Docusaurus's default blog post lists into a visually appealing card-based layout. You'll learn how to implement a reusable multi-part `` component, and then create a custom `` component to display post-specific information. The tutorial walks you through creating a local Docusaurus plugin to override the default `/blog/tags/:tag` route, and a new page component to render the cards. It also covers utility scripts for fetching post metadata and generating slugs. In this article, we'll learn how to create a card from a blog post. If you're [using Docusaurus for your blog](/blog/docusaurus-docker-own-blog), you might be looking for some ways to improve the layout of pages. Instead of displaying posts as a list, let's see how we can display them as **cards**. In this guide, we'll walk through how to create this. You've been just asked to copy/paste files to your site and make a small change in your configuration file. ![Example of a card](./images/cards.webp) This will imply a big number of files but the idea is then to reuse created components / files for later use. ## Using the Reusable Card component of Docux First, we'll retrieve the [Reusable Card Component](https://docuxlab.com/blog/card-component-docusaurus-infima/) of our friend, ![Docux](/img/docux.webp)[Docux](https://github.com/Juniors017). It's a set of files you have to create; let's proceed. > **Information:** > > That one can be retrieved too on the [Docusaurus Community](https://docusaurus.community/knowledge/component-library/new/Card/) site but perhaps not up to date. In your Docusaurus site, please create these files: **src/components/Card/index.tsx** ```typescript import type { CSSProperties, JSX, ReactNode } from "react"; import clsx from "clsx"; // clsx helps manage conditional className names in a clean and concise manner. interface Props { /** Custom classes for the container card */ className?: string; /** Custom styles for the container card */ style?: CSSProperties; /** Content to be included within the card */ children?: ReactNode; /** Shadow under the card. Expected values: low (lw), medium (md), tall (tl) */ shadow?: "lw" | "md" | "tl"; } const Card = ({ className, style, children, shadow }: Props): JSX.Element => { const cardShadow = shadow ? `item shadow--${shadow}` : ""; return (
{children}
); }; export default Card; ``` **src/components/Card/styles.module.css** ```css .truncate p { display: -webkit-box; -webkit-line-clamp: 3; line-clamp: 3; -webkit-box-orient: vertical; overflow: hidden; text-overflow: ellipsis; margin-bottom: 0; overflow-wrap: break-word; max-height: 4.5em; /* 3 lines × 1.5em line-height */ line-height: 1.5em; } ``` **src/components/Card/CardBody/index.tsx** ```typescript import type { CSSProperties, JSX, ReactNode } from "react"; import clsx from "clsx"; import styles from "../styles.module.css"; import { buildTextClasses, type CardTextOptions } from "../utils"; interface Props extends CardTextOptions { /** className for the container card */ className?: string; /** Custom styles for the container card */ style?: CSSProperties; /** Content to be included within the card */ children?: ReactNode; } const CardBody = ({ className, style, children, textAlign, variant, italic = false, noDecoration = false, transform, truncate = false, weight, }: Props): JSX.Element => { const { text, textColor, textItalic, textDecoration, textType, textTruncate, textWeight, } = buildTextClasses( { textAlign, variant, italic, noDecoration, transform, truncate, weight }, styles.truncate, ); return (
{children}
); }; export default CardBody; ``` **src/components/Card/CardFooter/index.tsx** ```typescript import type { CSSProperties, JSX, ReactNode } from "react"; import clsx from "clsx"; import styles from "../styles.module.css"; import { buildTextClasses, type CardTextOptions } from "../utils"; interface Props extends CardTextOptions { className?: string; style?: CSSProperties; children?: ReactNode; } const CardFooter = ({ className, style, children, textAlign, variant, italic = false, noDecoration = false, transform, truncate = false, weight, }: Props): JSX.Element => { const { text, textColor, textItalic, textDecoration, textType, textTruncate, textWeight, } = buildTextClasses( { textAlign, variant, italic, noDecoration, transform, truncate, weight }, styles.truncate, ); return (
{children}
); }; export default CardFooter; ``` **src/components/Card/CardHeader/index.tsx** ```typescript import type { CSSProperties, JSX, ReactNode } from "react"; import clsx from "clsx"; // clsx helps manage conditional className names in a clean and concise manner. import styles from "../styles.module.css"; import { buildTextClasses, type CardTextOptions } from "../utils"; interface Props extends CardTextOptions { /** className for the container card */ className?: string; /** Custom styles for the container card */ style?: CSSProperties; /** Content to be included within the card */ children?: ReactNode; } const CardHeader = ({ className, style, children, textAlign, variant, italic = false, noDecoration = false, transform, truncate = false, weight, }: Props): JSX.Element => { const { text, textColor, textItalic, textDecoration, textType, textTruncate, textWeight, } = buildTextClasses( { textAlign, variant, italic, noDecoration, transform, truncate, weight }, styles.truncate, ); return (
{children}
); }; export default CardHeader; ``` **src/components/Card/CardImage/index.tsx** ```typescript /** * CardImage Component * * Renders an image for a card layout with optional lazy loading and * customizable size. Automatically resolves the image URL using Docusaurus's * `useBaseUrl` hook. Applies default styling via the "card__image" class * and supports additional custom styles. * * Notes: * - Using `width` and `height` helps reduce layout shift by reserving space * for the image before it loads. * - You can also override sizing via CSS or the `style` prop if more flexibility is needed. */ import type { CSSProperties, JSX } from "react"; import clsx from "clsx"; import useBaseUrl from "@docusaurus/useBaseUrl"; interface Props { /** Optional additional CSS classes to apply. */ className?: string; /** Inline styles for the image element. */ style?: CSSProperties; /** Relative or absolute path to the image. */ cardImageUrl: string; /** Alternative text for accessibility. */ alt: string; /** Optional tooltip text shown on hover. */ title?: string; /** If true, enables `loading="lazy"` to defer image loading until visible. */ lazy?: boolean; /** Optional width of the image in pixels. */ width?: number; /** Optional height of the image in pixels. */ height?: number; } const CardImage = ({ className, style, cardImageUrl, alt, title, lazy = true, width, height, }: Props): JSX.Element => { const generatedCardImageUrl = useBaseUrl(cardImageUrl); return ( {alt} ); }; export default CardImage; ``` So right now, you've created six files on your disk. Before going any further in this tutorial, let's first play around with the Card component and see if everything is saved correctly. Please create a new post in your `blog` folder but pay attention to the extension, it should be a `.mdx` file (because we'll add some code that should be interpreted). **blog/card.mdx** ```mdx import Card from "@site/src/components/Card"; import CardFooter from "@site/src/components/Card/CardFooter"; import CardImage from "@site/src/components/Card/CardImage";
``` If you run your blog right now, you should get this: ![Docux card](./images/docux_sample.webp) > **Note:** > > If you want to retrieve the cute dino image, just grab it from here and store it in your `/static/img` folder with `docux.webp` as a name. > > You can reuse any other image for sure. ## Nice, it works. Let's continue with a practical sample In this article, we'll override the standard page with the list of tags. As you know, natively, Docusaurus can display a page with [the list of tags](/blog/docusaurus-tags) used across your articles if you access the **/blog/tags** page. So for my own blog, the page is and you'll get something like this: ![The tags page](./images/tags.webp) By clicking on a specific tag, Docusaurus will show a list of posts for that tag and we'll change this. For instance, this: ![Before our tag override](./images/tag_before.webp) > **Information:** > > It can be nice but ... OK, I have to scroll a lot before seeing all articles and find the one that might interest me. We'll change this to a list of post cards. As an example, on my blog, I'm also writing about [python](https://www.avonture.be/blog/tags/python) and here is how I'm rendering the page: ![The Python tag page](./images/tag_python.webp) This concrete example will allow us to implement two Docusaurus concepts: **the concept of plugins and that of components**. ## Overriding the /blog/tags/tag page by creating a plugin Please create the file here above. **plugins/docusaurus-plugin-tag-route/index.cjs** ```cjs /** * Docusaurus Plugin: tag-route * * Registers the `/blog/tags/` pages rendered by `TagArticlesPage`. * * Why one route per tag instead of a single `/blog/tags/:tag` (TODO 0092): * Docusaurus's `handleBrokenLinks` resolves links against the list of *registered* * routes, and a parameterized path matches nothing there. With a single `:tag` route * every `` in the corpus was reported as broken, which is * why `onBrokenLinks` had to be set to "ignore" site-wide — and a genuinely dead link * then went out silently with it. Enumerating the real tags at build time makes those * links resolvable, so link checking can be switched back on. * * Note this is *not* the blog plugin's own tag listing: that one lives at * `/blog/tags/tags/` (the doubled segment comes from blog/tags.yml's `permalink` * values being prefixed with the `/blog/tags` base), so the two never collide. */ const path = require("path"); const { normalizeUrl } = require("@docusaurus/utils"); const { listTagSlugs } = require("../lib/blog-taxonomy.cjs"); module.exports = function (context) { return { name: "docusaurus-plugin-tag-route", // Routes are enumerated from article frontmatter, so a new tag/series would // otherwise only get a route on the next dev-server restart. Watching the corpus // makes `yarn start` pick it up on save, like the parameterized route used to. getPathsToWatch() { return [path.join(context.siteDir, "blog", "**", "index.{md,mdx}")]; }, async contentLoaded({ actions }) { for (const slug of listTagSlugs(context.siteDir)) { actions.addRoute({ // MUST go through `baseUrl`: under a non-default locale it becomes `/fr/`, and a // hardcoded `/blog/tags/` registers a route the locale-prefixed links never // reach. That mismatch reported 2520 broken links on the `fr` build — the routes // existed as `/blog/tags/` while every link pointed at // `/fr/blog/tags/`. See TODO 0119. path: normalizeUrl([context.baseUrl, "blog/tags", slug]), component: "@site/src/components/Blog/Tags/TagArticlesPage", exact: true, }); } }, }; }; ``` Take a few seconds to read this short script: as you can see that one will tell Docusaurus to no longer use its own standard `/blog/tags/:tag` page but ours (i.e. `src/components/Blog/Tags/TagArticlesPage`). Let's create that one. ## Creating the TagArticlesPage Please create the file below. It's the `TagArticlesPage` function that'll be called by Docusaurus when it displays a specific tag. **src/components/Blog/Tags/TagArticlesPage.tsx** ```typescript import type { JSX } from "react"; import { createSlug } from "@site/src/components/Blog/utils/slug"; import { useBlogMetadata } from "@site/src/components/Blog/utils/posts"; import { useLocation, matchPath } from "@docusaurus/router"; import useDocusaurusContext from "@docusaurus/useDocusaurusContext"; import { useBaseUrlUtils } from "@docusaurus/useBaseUrl"; import Layout from "@theme/Layout"; import Link from "@docusaurus/Link"; import Translate, { translate } from "@docusaurus/Translate"; import styles from "./styles.module.css"; import PostCard from "@site/src/components/Blog/PostCard"; import Head from "@docusaurus/Head"; import FollowFeed from "@site/src/components/FollowFeed"; import { useTagLabel } from "@site/src/components/Blog/utils/tagsI18n"; import { useSourceLocaleUrls } from "@site/src/components/Blog/utils/localeUrls"; type Tag = string | { label: string }; export default function TagArticlesPage(): JSX.Element { const location = useLocation(); // Hooks must run before any early return. const posts = useBlogMetadata(); const tagLabel = useTagLabel(); const { isDefaultLocale, sourceLabel, sourceLocale, sourceUrl } = useSourceLocaleUrls(); const { withBaseUrl } = useBaseUrlUtils(); // The pattern MUST carry `baseUrl`: under the `fr` locale the pathname is `/fr/blog/tags/` // and a hardcoded pattern silently matches nothing, rendering the "not found" branch on a // perfectly valid page (TODO 0119). const { siteConfig } = useDocusaurusContext(); const base = siteConfig.baseUrl.replace(/\/$/, ""); const match = matchPath<{ slug: string }>(location.pathname, { path: `${base}/blog/tags/:slug`, exact: true, }); const rawTag = match?.params?.slug; if (!rawTag) { return (

No tag specified.

Go back to all tags
); } // Local helper, unrelated to `useTagLabel`: it reads the raw value out of a front-matter // entry, which may be a bare string or a `{ label }` object. What comes out is the KEY. const getTagKey = (t: Tag) => (typeof t === "string" ? t : t.label); // Find original tag name based on slug let displayTag = rawTag; for (const post of posts) { const foundTag = (post.tags || []).find( (t) => createSlug(getTagKey(t)) === rawTag ); if (foundTag) { displayTag = getTagKey(foundTag); break; } } // `displayTag` is the front-matter KEY; this is what the reader sees. Resolving it here, once, // also closes the inconsistency noted below: the

used to print the raw key ("ai") while // the feed button right under it printed the real label ("Artificial Intelligence (AI)"). const displayLabel = tagLabel(displayTag); // Filter and sort posts by slug-matched tag (most recent first) const taggedPosts = posts .filter((post) => post.tags?.some((t) => createSlug(getTagKey(t)) === rawTag) ) .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()); // Descending if (taggedPosts.length === 0) { return (

{'No articles found with tag "{label}"'}

Browse all tags
); } const feedUrl = `/blog/tags/${rawTag}/rss.xml`; return (

{"Articles tagged: {label}"}

{/* This route is registered by docusaurus-plugin-tag-route, not by the blog plugin, so Docusaurus injects no feed autodiscovery of its own here — same reasoning as src/components/MarkdownAlternate. */} {/* `feedUrl` is a hand-built path to a per-locale static file, so it needs the prefix; the second points at the source language, which covers the whole blog. Helmet de-duplicates on `href`, so both are kept. */} {!isDefaultLocale && ( )}
{taggedPosts.map((post) => ( ))}
); } ``` As you can see at the very top of the `TagArticlesPage.tsx` file, we're importing a few files. Some already exist in your Docusaurus site; some should be created. There are three files we should create ## The slug generator **src/components/Blog/utils/slug.ts** ```typescript /** * Converts a string into a URL-friendly slug. * * This function: * - Converts the string to lowercase * - Normalizes accented characters (e.g., accented e to plain e) * - Removes diacritics and special characters * - Replaces spaces with hyphens * - Collapses multiple hyphens into one * - Trims leading and trailing hyphens * * @param text - The input string to convert. * @returns The slugified version of the input. */ export function createSlug(text: string): string { return text .replace(/([a-z0-9])([A-Z])/g, "$1-$2") // camelCase to kebab-case .toLowerCase() .normalize("NFD") // Decomposes accented characters .replace(/[\u0300-\u036f]/g, "") // Removes diacritics .replace(/[^a-z0-9\s-]/g, "") // Removes special characters .replace(/\s+/g, "-") // Replaces spaces with hyphens .replace(/-+/g, "-") // Collapses multiple hyphens .replace(/^-+|-+$/g, ""); // Trims leading/trailing hyphens } ``` ## The getBlogMetaData function We need a function to loop all our existing blog posts (all `.md` or `.mdx` files under the `blog` folder) and collect information like the post title, image, slug and so on. **src/components/Blog/utils/posts.ts** ````typescript /** * 🧠 getBlogMetadata * * Extracts metadata from all MDX blog posts located in the `/blog` directory. * Uses Webpack's `require.context` to dynamically load and parse frontmatter * from each post, returning a structured array of metadata objects. * * 🔍 Behavior: * - Resolves permalinks based on `slug` or folder structure * - Normalizes image paths for static assets * - Filters out invalid or missing entries * * 📦 Returned metadata includes: * - `title`: Post title * - `description`: Short summary * - `image`: Resolved image path * - `draft`: Boolean flag for unpublished posts * - `unlisted`: Boolean flag for hidden posts * - `permalink`: URL path to the post * - `tags`: Array of tags * - `mainTag`: Primary tag (optional); used by the RelatedBlogPost component * - `authors`: Array of author names * - `date`: Publication date * - `series`: Series name (optional); used by the SeriesBlogPost component * * 🛠️ Usage: * ```ts * import { getBlogMetadata } from './getBlogMetadata'; * const posts = getBlogMetadata(); * ``` * * ⚠️ Note: * This function is intended for use in static site generation or client-side rendering * where Webpack's `require.context` is available. */ export interface BlogPostMetadata { title: string; description?: string; image?: string; draft: boolean; unlisted: boolean; permalink: string; tags: string[]; mainTag: string | null; authors: string[]; date?: string; series: string | null; } const posts = require.context("../../../../blog", true, /\.mdx?$/); export function getBlogMetadata(): BlogPostMetadata[] { return posts .keys() .map((key): BlogPostMetadata => { const post = posts(key) as { frontMatter: Record }; const dir = key.replace(/\/index\.mdx?$/, "").replace(/^\.\//, ""); let permalink: string; if (typeof post.frontMatter.slug === "string") { permalink = post.frontMatter.slug.startsWith("/") ? post.frontMatter.slug : `/blog/${post.frontMatter.slug.replace(/^\//, "")}`; } else { permalink = `/blog/${dir}/`; } let imageUrl = post.frontMatter.image as string | undefined; if (imageUrl && imageUrl.startsWith("./")) { imageUrl = `/blog/${dir}/${imageUrl.replace("./", "")}`; } return { title: post.frontMatter.title as string, description: post.frontMatter.description as string | undefined, image: imageUrl, draft: Boolean(post.frontMatter.draft), unlisted: Boolean(post.frontMatter.unlisted), permalink, tags: (post.frontMatter.tags as string[]) || [], mainTag: (post.frontMatter.mainTag as string) || null, authors: (post.frontMatter.authors as string[]) || [], date: post.frontMatter.date as string | undefined, series: (post.frontMatter.series as string) || null, }; }) .filter(Boolean); } ```` ## Our PostCard component And, finally, we need our PostCard component; the one that will display a blog post as a card. You can see, in the top of the code, that we're importing a few parts of the [Card component](https://docusaurus.community/knowledge/component-library/new/Card/) of Docux. **src/components/Blog/PostCard/index.tsx** ```typescript /** * ♣️ PostCard component * * A reusable Docusaurus component that displays a blog post preview card. * It shows the post image (with fallback), title (as a link), and description. * * Accessibility: * - The title is wrapped in a semantic link with an aria-label for screen readers. * - The image includes alt and title attributes. * * Styling: * - Uses Infima utility classes for layout and spacing. * - Custom styles can be applied via `styles.module.css`. * * Location: src/components/Blog/PostCard/index.tsx */ import type { JSX } from "react"; import Card from "@site/src/components/Card"; import CardBody from "@site/src/components/Card/CardBody"; import CardImage from "@site/src/components/Card/CardImage"; import Link from "@docusaurus/Link"; import styles from "./styles.module.css"; interface FormattedDateProps { date?: string; layout: "big" | "small"; } /** Renders a formatted date string. */ function FormattedDate({ date, layout }: FormattedDateProps): JSX.Element | null { if (!date) { return null; } return (

{new Date(date).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", })}

); } interface Post { permalink: string; image?: string; title: string; description?: string; date?: string; } interface Props { post: Post; layout?: "big" | "small"; defaultImage?: string; } export default function PostCard({ post, layout = "big", defaultImage = "/img/default.jpg", }: Props): JSX.Element { const { permalink, image, title, description, date } = post; if (layout === "small") { return (
{title}

{title}

{description && (
{description}
)}
Read more
); } // Default "big" layout return (

{title} →

{description &&

{description}

}
); } ``` Finally, we'll create a CSS file to allow us to do some customization: **src/components/Blog/PostCard/styles.module.css** ```css .description { font-size: 12px; } .date { color: #888; font-size: 0.95em; margin-bottom: 8; font-style: italic; } ``` ## We need to load our plugin We're almost done. Remember, the very first file we've created was `plugins/docusaurus-plugin-tag-route/index.cjs`; a plugin. Please edit your existing `docusaurus.config.js` file like below illustrated: **docusaurus.config.js** ```javascript import pluginTagRoute from "./plugins/docusaurus-plugin-tag-route/index.cjs"; const config = { // [...] plugins: [ // [...] [pluginTagRoute, {}], ], // [...] }; ``` i.e. 1. You have to import the plugin at the top of your file 2. Then in the `plugins` section, you have to add a new line to load your imported plugin. We're almost finished! > **Caution:** > > Please stop and restart your Docusaurus server. On my case ([I'm using Docker](/blog/running-docusaurus-with-docker)), I just need to stop and restart my container. If everything is going fine after the restart (no error message), please visit your website tags page and open a tag. You should now see your posts as cards. Congratulations! In [next articles](/blog/docusaurus-relatedposts), we'll reuse this concept of post cards. Stay tuned! ## Extra If you want your blog posts to be listed from the newest one to the oldest, please use this script. But make sure every blog post you have has a `date` field in its YAML front matter. **src/components/Blog/Tags/TagArticlesPage.tsx** ```typescript import { createSlug } from "@site/src/components/Blog/utils/slug"; import { getBlogMetadata } from "@site/src/components/Blog/utils/posts"; import { useLocation } from "@docusaurus/router"; import Layout from "@theme/Layout"; import Link from "@docusaurus/Link"; import PostCard from "@site/src/components/Blog/PostCard"; function getTagFromPathname(pathname: string): string | null { const match = pathname.match(/\/blog\/tags\/([^/]+)/); return match ? decodeURIComponent(match[1]) : null; } export default function TagArticlesPage() { const location = useLocation(); const rawTag = getTagFromPathname(location.pathname); if (!rawTag) { return (

No tag specified.

Go back to all tags
); } const posts = getBlogMetadata(); // Find original tag name based on slug const allTags = Array.from(new Set(posts.flatMap((post) => post.tags || []))); const displayTag = allTags.find((t) => createSlug(String(t)) === rawTag) || rawTag; // highlight-start // Filter and sort posts by slug-matched tag (most recent first) const taggedPosts = posts .filter((post) => post.tags?.some((t) => createSlug(String(t)) === rawTag)) .sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime()); // Descending // highlight-end if (taggedPosts.length === 0) { return (

No articles found with tag "{displayTag}"

Browse all tags
); } return (

Articles tagged: {displayTag}

{taggedPosts.map((post) => ( ))}
); } ```