如何自定义Docusaurus生成索引页中的文件项（图标、描述）？

核心思路 #

替换自动生成的索引页为自定义MDX页面，通过文档frontmatter添加自定义字段，手动构建带图标和自定义描述的卡片列表。

具体步骤 #

1. 给教程文档添加自定义frontmatter字段 #

在tutorials目录下的每个教程文件（如01-first-tutorial.md）开头的frontmatter中，新增icon和customDescription字段：

---
title: 第一个教程
icon: 🚀
customDescription: 这里是自定义的教程描述，替代默认提取的首段内容
---

• 图标可以用emoji，也可以用本地SVG路径（如/img/icons/tutorial-1.svg）
• customDescription填写你想要展示的自定义文本

2. 创建自定义索引页 #

在tutorials目录下新建index.mdx文件，替换默认自动生成的索引页。文件内容如下：

import { Card, CardContent, CardHeader, CardTitle } from '@docusaurus/components';
import Link from '@docusaurus/Link';
import { useDocs } from '@docusaurus/theme-common/internal';

export default function TutorialsIndex() {
  // 获取所有文档数据
  const { docs } = useDocs();
  // 筛选出tutorials目录下的文档
  const tutorialDocs = docs.filter(doc => doc.sourceDirName === 'tutorials');

  return (
    <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
      {tutorialDocs.map(doc => (
        <Link key={doc.id} to={doc.path} className="no-underline">
          <Card>
            <CardHeader className="flex items-center gap-2">
              {/* 渲染图标 */}
              {typeof doc.frontMatter.icon === 'string' ? (
                <span className="text-2xl">{doc.frontMatter.icon}</span>
              ) : (
                doc.frontMatter.icon
              )}
              <CardTitle>{doc.frontMatter.title}</CardTitle>
            </CardHeader>
            <CardContent>
              {/* 优先显示自定义描述， fallback到默认描述 */}
              {doc.frontMatter.customDescription || doc.description}
            </CardContent>
          </Card>
        </Link>
      ))}
    </div>
  );
}

3. 调整样式（可选） #

如果需要更贴近目标效果的样式，可以自定义CSS类，在src/css/custom.css中添加：

.card {
  transition: transform 0.2s ease;
}
.card:hover {
  transform: translateY(-4px);
  box-shadow: 0 8px 16px rgba(0,0,0,0.1);
}

为什么之前的尝试没成功？ #

• 直接用DocCardList会默认读取文档的description（提取首段）和默认样式，无法直接自定义图标和描述
• 仅修改教程文件的frontmatter但未替换自动索引页，自动生成的页面不会读取自定义字段用于条目展示

内容的提问来源于stack exchange，提问作者NoSQLKnowHow