📦 plugin-content-blog

提供 博客 功能，是 Docusaurus 默认的博客插件。

某些功能仅在生产环境可用

此 Feed 功能 通过提取构建输出生效，并且仅在生产环境激活。

安装

npm

npm install --save @docusaurus/plugin-content-blog

Yarn

yarn add @docusaurus/plugin-content-blog

pnpm

pnpm add @docusaurus/plugin-content-blog

Bun

bun add @docusaurus/plugin-content-blog

提示

如果您使用预设 @docusaurus/preset-classic，则无需将此插件作为依赖项安装。

您可以通过 预设选项来配置此插件。

配置

接受的字段

名称	类型	默认值	描述
path	string	'blog'	博客内容目录在文件系统上的路径，相对于站点目录。
editUrl	string | EditUrlFn	undefined	编辑站点的基本 URL。最终 URL 由 editUrl + relativePostPath 计算得出。使用函数可以对每个文件进行更精细的控制。完全省略此变量将禁用编辑链接。
editLocalizedFiles	boolean	false	编辑 URL 将指向本地化文件，而非原始的非本地化文件。当 editUrl 为函数时，此项将被忽略。
blogTitle	string	'Blog'	博客页面标题，用于更好的 SEO。
blogDescription	string	'Blog'	博客页面元描述，用于更好的 SEO。
blogSidebarCount	number | 'ALL'	5	在博客侧边栏中显示的博客文章元素数量。设置为 'ALL' 以显示所有博客文章；设置为 0 以禁用。
blogSidebarTitle	string	'Recent posts'	博客侧边栏的标题。
routeBasePath	string	'blog'	站点的博客部分的 URL 路由。请勿包含尾随斜杠。使用 / 将博客置于根路径。
tagsBasePath	string	'tags'	博客标签部分的 URL 路由。将附加到 routeBasePath。
pageBasePath	string	'page'	博客页面部分的 URL 路由。将附加到 routeBasePath。
archiveBasePath	string | null	'archive'	博客归档部分的 URL 路由。将附加到 routeBasePath。请勿包含尾随斜杠。使用 null 禁用归档生成。
authorsBasePath	string	'authors'	博客作者页面的 URL 路由。将附加到 path。
include	string[]	['**/*.{md,mdx}']	匹配要构建的 Markdown 文件的 glob 模式数组，相对于内容路径。
exclude	string[]	See example configuration	匹配要排除的 Markdown 文件的 glob 模式数组。作为基于 include 选项的细化。
postsPerPage	number | 'ALL'	10	列表页面每页显示的帖子数量。使用 'ALL' 在一个列表页面上显示所有帖子。
blogListComponent	string	'@theme/BlogListPage'	博客列表页面的根组件。
blogPostComponent	string	'@theme/BlogPostPage'	每个博客文章页面的根组件。
blogTagsListComponent	string	'@theme/BlogTagsListPage'	标签列表页面的根组件。
blogTagsPostsComponent	string	'@theme/BlogTagsPostsPage'	"包含标签的帖子"页面的根组件。
blogArchiveComponent	string	'@theme/BlogArchivePage'	博客归档页面的根组件。
blogAuthorsPostsComponent	string	'@theme/Blog/Pages/BlogAuthorsPostsPage'	博客作者页面的根组件。
blogAuthorsListComponent	string	'@theme/Blog/Pages/BlogAuthorsListPage'	博客作者页面索引的根组件。
remarkPlugins	any[]	[]	传递给 MDX 的 Remark 插件。
rehypePlugins	any[]	[]	传递给 MDX 的 Rehype 插件。
rehypePlugins	any[]	[]	传递给 MDX 的 Recma 插件。
beforeDefaultRemarkPlugins	any[]	[]	在默认 Docusaurus Remark 插件之前，传递给 MDX 的自定义 Remark 插件。
beforeDefaultRehypePlugins	any[]	[]	在默认 Docusaurus Rehype 插件之前，传递给 MDX 的自定义 Rehype 插件。
truncateMarker	RegExp	/<!--\s*truncate\s*-->/ | \{\/\*\s*truncate\s*\*\/\}/	标记摘要结束位置的截断标记。
showReadingTime	boolean	true	显示博客文章的预计阅读时间。
readingTime	ReadingTimeFn	The default reading time	用于自定义显示阅读时间数字的回调函数。
authorsMapPath	string	'authors.yml'	作者映射文件的路径，相对于博客内容目录。
feedOptions	See below	{type: ['rss', 'atom']}	博客 Feed。
feedOptions.type	FeedType | FeedType[] | 'all' | null	必需	要生成的 Feed 类型。使用 null 禁用生成。
feedOptions.createFeedItems	CreateFeedItemsFn | undefined	undefined	一个可选函数，可用于转换和/或过滤 Feed 中的项目。
feedOptions.limit	number | null | false	20	将 Feed 限制为指定数量的帖子，false 或 null 表示所有条目。默认为 20。
feedOptions.title	string	siteConfig.title	Feed 标题。
feedOptions.description	string	`${siteConfig.title} Blog`	Feed 描述。
feedOptions.copyright	string	undefined	版权信息。
feedOptions.xslt	boolean | FeedXSLTOptions	undefined	允许使用 XSLT 为博客 XML Feed 设置样式，以便浏览器良好渲染。
feedOptions.language	string (See documentation for possible values)	undefined	Feed 的语言元数据。
sortPosts	'descending' | 'ascending'	'descending'	控制博客文章的排序方向。
processBlogPosts	ProcessBlogPostsFn	undefined	一个可选函数，可用于转换博客文章（过滤、修改、删除等）。
showLastUpdateAuthor	boolean	false	是否显示最后更新博客文章的作者。
showLastUpdateTime	boolean	false	是否显示博客文章的最后更新日期。这需要在构建期间访问 Git 历史记录，因此无法正确处理浅克隆（CI 系统常见的默认设置）。使用 GitHub actions/checkout 时，请使用 fetch-depth: 0。
tags	string | false | null | undefined	tags.yml	列出预定义标签的 YAML 标签文件路径。相对于博客内容目录。
onInlineTags	'ignore' | 'log' | 'warn' | 'throw'	warn	当博客文章包含内联标签（不出现在预定义标签列表中的标签，通常是 tags.yml）时，插件的行为。
onUntruncatedBlogPosts	'ignore' | 'log' | 'warn' | 'throw'	warn	当博客文章不包含截断标记时，插件的行为。

类型

EditUrlFn

type EditUrlFunction = (params: {
  blogDirPath: string;
  blogPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

ReadingTimeFn

type ReadingTimeOptions = {
  wordsPerMinute: number;
};

type ReadingTimeCalculator = (params: {
  content: string;
  locale: string;
  frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
  options?: ReadingTimeOptions;
}) => number;

type ReadingTimeFn = (params: {
  content: string;
  locale: string;
  frontMatter: BlogPostFrontMatter & Record<string, unknown>;
  defaultReadingTime: ReadingTimeCalculator;
}) => number | undefined;

FeedType

type FeedType = 'rss' | 'atom' | 'json';

FeedXSLTOptions

允许使用 XSLT 为博客 XML Feed 设置样式，以便浏览器良好渲染。

• 使用 true 允许博客使用其内置的 .xsl 和 .css 文件来设置博客 Feed 的样式
• 使用虚值（undefined | null | false）来禁用此功能
• 使用 string 提供自定义 .xsl 文件的文件路径，该路径相对于博客内容文件夹。按照约定，您必须提供一个同名的 .css 文件。

type FeedXSLTOptions =
  | boolean
  | undefined
  | null
  | {
      rss?: string | boolean | null | undefined;
      atom?: string | boolean | null | undefined;
    };

CreateFeedItemsFn

type CreateFeedItemsFn = (params: {
  blogPosts: BlogPost[];
  siteConfig: DocusaurusConfig;
  outDir: string;
  defaultCreateFeedItemsFn: CreateFeedItemsFn;
}) => Promise<BlogFeedItem[]>;

ProcessBlogPostsFn

type ProcessBlogPostsFn = (params: {
  blogPosts: BlogPost[];
}) => Promise<void | BlogPost[]>;

示例配置

您可以通过预设选项或插件选项配置此插件。

提示

大多数 Docusaurus 用户通过预设选项配置此插件。

预设选项

如果您使用预设，请通过 预设选项配置此插件

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          path: 'blog',
          // Simple use-case: string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Advanced use-case: functional editUrl
          editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
            `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
          editLocalizedFiles: false,
          blogTitle: 'Blog title',
          blogDescription: 'Blog',
          blogSidebarCount: 5,
          blogSidebarTitle: 'All our posts',
          routeBasePath: 'blog',
          include: ['**/*.{md,mdx}'],
          exclude: [
            '**/_*.{js,jsx,ts,tsx,md,mdx}',
            '**/_*/**',
            '**/*.test.{js,jsx,ts,tsx}',
            '**/__tests__/**',
          ],
          postsPerPage: 10,
          blogListComponent: '@theme/BlogListPage',
          blogPostComponent: '@theme/BlogPostPage',
          blogTagsListComponent: '@theme/BlogTagsListPage',
          blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
          remarkPlugins: [require('./my-remark-plugin')],
          rehypePlugins: [],
          beforeDefaultRemarkPlugins: [],
          beforeDefaultRehypePlugins: [],
          truncateMarker: /<!--\s*(truncate)\s*-->/,
          showReadingTime: true,
          feedOptions: {
            type: '',
            title: '',
            description: '',
            copyright: '',
            language: undefined,
            createFeedItems: async (params) => {
              const {blogPosts, defaultCreateFeedItems, ...rest} = params;
              return defaultCreateFeedItems({
                // keep only the 10 most recent blog posts in the feed
                blogPosts: blogPosts.filter((item, index) => index < 10),
                ...rest,
              });
            },
          },
        },
      },
    ],
  ],
};

插件选项

如果您使用的是独立插件，请直接向插件提供选项

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        path: 'blog',
        // Simple use-case: string editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // Advanced use-case: functional editUrl
        editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
          `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
        editLocalizedFiles: false,
        blogTitle: 'Blog title',
        blogDescription: 'Blog',
        blogSidebarCount: 5,
        blogSidebarTitle: 'All our posts',
        routeBasePath: 'blog',
        include: ['**/*.{md,mdx}'],
        exclude: [
          '**/_*.{js,jsx,ts,tsx,md,mdx}',
          '**/_*/**',
          '**/*.test.{js,jsx,ts,tsx}',
          '**/__tests__/**',
        ],
        postsPerPage: 10,
        blogListComponent: '@theme/BlogListPage',
        blogPostComponent: '@theme/BlogPostPage',
        blogTagsListComponent: '@theme/BlogTagsListPage',
        blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
        remarkPlugins: [require('./my-remark-plugin')],
        rehypePlugins: [],
        beforeDefaultRemarkPlugins: [],
        beforeDefaultRehypePlugins: [],
        truncateMarker: /<!--\s*(truncate)\s*-->/,
        showReadingTime: true,
        feedOptions: {
          type: '',
          title: '',
          description: '',
          copyright: '',
          language: undefined,
          createFeedItems: async (params) => {
            const {blogPosts, defaultCreateFeedItems, ...rest} = params;
            return defaultCreateFeedItems({
              // keep only the 10 most recent blog posts in the feed
              blogPosts: blogPosts.filter((item, index) => index < 10),
              ...rest,
            });
          },
        },
      },
    ],
  ],
};

Markdown Front Matter

Markdown 文档可以使用以下 Markdown Front Matter 元数据字段，字段两侧由一行 --- 包裹。

接受的字段

名称	类型	默认值	描述
authors	Authors	undefined	博客文章作者列表（或单一作者）。阅读 authors 指南 了解更多解释。即使是单作者博客文章，也请优先使用 authors，而非 author_* Front Matter 字段。
author	string	undefined	⚠️ 建议使用 authors。博客文章作者的姓名。
author_url	string	undefined	⚠️ 建议使用 authors。作者姓名将链接到的 URL。这可以是 GitHub、X、Facebook 个人资料 URL 等。
author_image_url	string	undefined	⚠️ 建议使用 authors。作者缩略图的 URL。
author_title	string	undefined	⚠️ 建议使用 authors。作者的描述。
title	string	Markdown title	博客文章标题。
title_meta	string	frontMatter.title	博客文章的 SEO 元数据标题，用于 <head> 中的 <title> 和 og:title。当显示标题和 SEO 标题需要不同时，允许覆盖 title。
sidebar_label	string	title	博客侧边栏的自定义标签，替换默认标签（title）。
date	string	File name or file creation time	博客文章创建日期。如果未指定，则可以从文件或文件夹名称中提取，例如：2021-04-15-blog-post.mdx、2021-04-15-blog-post/index.mdx、2021/04/15/blog-post.mdx。否则，它将是 Markdown 文件的创建时间。
tags	Tag[]	undefined	一个字符串列表或包含 label 和 permalink 两个字符串字段的对象列表，用于标记您的帖子。字符串可以是 标签文件（通常是 tags.yml）中键的引用。
draft	boolean	false	草稿博客文章仅在开发期间可用。
unlisted	boolean	false	未列出的博客文章在开发和生产环境中都可用。它们将在生产环境中“隐藏”，不被索引，从站点地图中排除，并且只能通过直接链接访问。
hide_table_of_contents	boolean	false	是否隐藏右侧的目录。
toc_min_heading_level	number	2	目录中显示的最小标题级别。必须介于 2 和 6 之间，且小于或等于最大值。
toc_max_heading_level	number	3	目录中显示的最大标题级别。必须介于 2 和 6 之间。
keywords	string[]	undefined	关键词元标签，它将成为 <head> 中的 <meta name="keywords" content="keyword1,keyword2,..."/>，供搜索引擎使用。
描述	string	Markdown 内容的第一行	文档的描述，它将成为 <head> 中的 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/>，供搜索引擎使用。
image	string	undefined	封面或缩略图，将作为 <head> 中的 <meta property="og:image" content="..."/>，增强社交媒体和消息平台上的链接预览。
slug	string	File path	允许自定义博客文章 URL (/<routeBasePath>/<slug>)。支持多种模式：slug: my-blog-post、slug: /my/path/to/blog/post、slug: /。
last_update	FrontMatterLastUpdate	undefined	允许覆盖最后更新的作者/日期。日期可以是任何可解析的日期字符串。

type FrontMatterLastUpdate = {date?: string; author?: string};

type Tag = string | {label: string; permalink: string};

// An author key references an author from the global plugin authors.yml file
type AuthorKey = string;

// Social platform name -> Social platform link
// Example: {MyPlatform: 'https://myplatform.com/myusername'}
// Pre-defined platforms
// ("x", "github", "twitter", "linkedin", "stackoverflow", "instagram", "bluesky", "mastodon", "threads", "twitch", "youtube") accept handles:
// Example: {github: 'slorber'}
type AuthorSocials = Record<string, string>;

type Author = {
  key?: AuthorKey;
  name: string;
  title?: string;
  url?: string;
  image_url?: string;
  socials?: AuthorSocials;
};

// The front matter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

示例

---
title: Welcome Docusaurus
authors:
  - slorber
  - yangshun
  - name: Joel Marcey
    title: Co-creator of Docusaurus 1
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
    socials:
      x: joelmarcey
      github: JoelMarcey
tags: [docusaurus]
description: This is my first post on Docusaurus.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

A Markdown blog post

标签文件

使用 tags 插件选项 配置 YAML 标签文件的路径。

按照约定，插件将在您的内容文件夹根目录查找 tags.yml 文件。

此文件可以包含预定义标签列表。您可以通过 tags Front Matter 在 Markdown 文件中通过其键引用这些标签。

保持标签一致性

使用标签文件，您可以确保您的插件内容集中标签使用的一致性。使用 onInlineTags: 'throw' 插件选项来强制执行此一致性，并防止使用即时声明的内联标签。

类型

所提供的标签文件的 YAML 内容应符合以下格式

type Tag = {
  label?: string; // Tag display label
  permalink?: string; // Tag URL pathname segment
  description?: string; // Tag description displayed in the tag page
};

type TagsFileInput = Record<string, Partial<Tag> | null>;

示例

tags.yml

releases:
  label: 'Product releases'
  permalink: '/product-releases'
  description: 'Content related to product releases.'

# A partial tag definition is also valid
announcements:
  label: 'Announcements'

# An empty tag definition is also valid
# Other attributes will be inferred from the key
emptyTag:

content.md

---
tags: [releases, announcements, emptyTag]
---

# Title

Content

作者文件

使用 authors 插件选项 配置 YAML 作者文件的路径。

按照约定，插件将在您的博客内容文件夹根目录查找 authors.yml 文件。

此文件可以包含预定义的 全局博客作者 列表。您可以通过 authors Front Matter 在 Markdown 文件中通过其键引用这些作者。

类型

所提供的作者文件的 YAML 内容应符合以下格式

type AuthorsMapInput = {
  [authorKey: string]: AuthorInput;
};

type AuthorInput = {
  name?: string;
  title?: string;
  description?: string;
  imageURL?: string;
  url?: string;
  email?: string;
  page?: boolean | {permalink: string};
  socials?: Record<string, string>;
  [customAuthorAttribute: string]: unknown;
};

示例

tags.yml

slorber:
  name: Sébastien Lorber
  title: Docusaurus maintainer
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png
  page: true
  socials:
    x: sebastienlorber
    github: slorber

jmarcey:
  name: Joel Marcey
  title: Co-creator of Docusaurus 1
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: [email protected]
  page:
    permalink: '/joel-marcey'
  socials:
    x: joelmarcey
    github: JoelMarcey

blog/my-blog-post.md

---
authors: [slorber, jmarcey]
---

# My Blog Post

Content

i18n

请先阅读 i18n 介绍。

翻译文件位置

• 基本路径：website/i18n/[locale]/docusaurus-plugin-content-blog
• 多实例路径：website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]
• JSON 文件：使用 docusaurus write-translations 提取
• Markdown 文件：website/i18n/[locale]/docusaurus-plugin-content-blog

示例文件系统结构

website/i18n/[locale]/docusaurus-plugin-content-blog
│
│ # translations for website/blog
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # translations for the plugin options that will be rendered
└── options.json