docs: explain swizzling DocCard #1207

Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,165 @@
	---
	id: doccard
	hide_title: true
	sidebar_label: DocCard Markdown
	title: DocCard Markdown
	description: Swizzle the DocCard component to render Markdown in card descriptions.
	---

	## Overview

	The default DocCard component used by Docusaurus displays the `description` field
	as plain text. Any Markdown inside the description is escaped rather than
	rendered. To support Markdown, you can swizzle the component and update it to use
	`@theme/Markdown`.

	## Swizzling the component

	Run the swizzle command from your site directory and choose the eject option
	when prompted:

	```bash
	npx docusaurus swizzle @docusaurus/theme-classic DocCard
	```

	This will create `src/theme/DocCard/index.tsx` in your project. Replace its
	contents with the following:

	```tsx title="src/theme/DocCard/index.tsx"
	import React, { type ReactNode } from "react";

	import isInternalUrl from "@docusaurus/isInternalUrl";
	import Link from "@docusaurus/Link";
	import type {
	PropSidebarItemCategory,
	PropSidebarItemLink,
	} from "@docusaurus/plugin-content-docs";
	import {
	useDocById,
	findFirstSidebarItemLink,
	} from "@docusaurus/plugin-content-docs/lib/client/docsUtils";
	import { usePluralForm } from "@docusaurus/theme-common";
	import { translate } from "@docusaurus/Translate";
	import type { Props } from "@theme/DocCard";
	import Heading from "@theme/Heading";
	import Markdown from "@theme/Markdown";
	import clsx from "clsx";

	import styles from "./styles.module.css";

	function useCategoryItemsPlural() {
	const { selectMessage } = usePluralForm();
	return (count: number) =>
	selectMessage(
	count,
	translate(
	{
	message: "1 item\|{count} items",
	id: "theme.docs.DocCard.categoryDescription.plurals",
	description:
	"The default description for a category card in the generated index about how many items this category includes",
	},
	{ count }
	)
	);
	}

	function CardContainer({
	className,
	href,
	children,
	}: {
	className?: string;
	href: string;
	children: ReactNode;
	}): ReactNode {
	return (
	<Link
	href={href}
	className={clsx("card padding--lg", styles.cardContainer, className)}
	>
	{children}
	</Link>
	);
	}

	function CardLayout({
	className,
	href,
	icon,
	title,
	description,
	}: {
	className?: string;
	href: string;
	icon: ReactNode;
	title: string;
	description?: string;
	}): ReactNode {
	return (
	<CardContainer href={href} className={className}>
	<Heading
	as="h2"
	className={clsx("text--truncate", styles.cardTitle)}
	title={title}
	>
	{icon} {title}
	</Heading>
	{description && (
	<Markdown
	className={clsx("text--truncate", styles.cardDescription)}
	title={description}
	>
	{description}
	</Markdown>
	)}
	</CardContainer>
	);
	}

	function CardCategory({ item }: { item: PropSidebarItemCategory }): ReactNode {
	const href = findFirstSidebarItemLink(item);
	const categoryItemsPlural = useCategoryItemsPlural();

	// Unexpected: categories that don't have a link have been filtered upfront
	if (!href) {
	return null;
	}

	return (
	<CardLayout
	className={item.className}
	href={href}
	icon="🗃️"
	title={item.label}
	description={item.description ?? categoryItemsPlural(item.items.length)}
	/>
	);
	}

	function CardLink({ item }: { item: PropSidebarItemLink }): ReactNode {
	const icon = isInternalUrl(item.href) ? "📄️" : "🔗";
	const doc = useDocById(item.docId ?? undefined);
	return (
	<CardLayout
	className={item.className}
	href={item.href}
	icon={icon}
	title={item.label}
	description={item.description ?? doc?.description}
	/>
	);
	}

	export default function DocCard({ item }: Props): ReactNode {
	switch (item.type) {
	case "link":
	return <CardLink item={item} />;
	case "category":
	return <CardCategory item={item} />;
	default:
	throw new Error(`unknown item type ${JSON.stringify(item)}`);
	}
	}
	```

Navigation Menu

Search code, repositories, users, issues, pull requests...

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

docs: explain swizzling DocCard #1207

Uh oh!

docs: explain swizzling DocCard #1207

Filter by extension

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing