📦 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[]	参见示例配置	要排除的 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	默认阅读时间	用于自定义显示的阅读时间数字的回调函数。
authorsMapPath	string	'authors.yml'	作者映射文件的路径，相对于博客内容目录。
feedOptions	见下文	{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（请参阅文档以获取可能的值）	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	当博客文章不包含截断标记时的插件行为。

Types

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
• 使用 falsy 值 (undefined | null | false) 禁用该功能
• 使用 string 提供一个文件路径，该文件路径相对于博客内容文件夹，该文件路径必须包含一个与文件名相同的 .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[]>;

Example configuration

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

提示

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

Preset options

If you use a preset, configure this plugin through the preset options:

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,
              });
            },
          },
        },
      },
    ],
  ],
};

Plugin options

If you are using a standalone plugin, provide options directly to the plugin:

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_meta	string	frontMatter.title	博客文章 SEO 元数据标题，用于 <head> 的 <title> 和 og:title。允许覆盖 title，当显示标题和 SEO 标题应该不同时。
sidebar_label	string	title	博客侧边栏的自定义标签，替换默认标签（title）。
date	string	文件名或文件创建时间	博客文章创建日期。如果未指定，可以从文件或文件夹名称中提取，例如 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 文件（通常是 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	关键词元标记，将成为 <meta name="keywords" content="keyword1,keyword2,..."/> 在 <head> 中，用于搜索引擎。
description	string	Markdown 内容的第一行	文档描述，将成为 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/> 在 <head> 中，用于搜索引擎。
image	string	undefined	封面或缩略图图像，将用作 <meta property="og:image" content="..."/> 在 <head> 中，增强社交媒体和消息平台上的链接预览。
slug	string	文件路径	允许自定义博客文章 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 文件。

此文件可以包含预定义标签的列表。您可以在 Markdown 文件中通过 tags 前置元数据引用这些标签的键。

保持标签一致性

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

类型

提供的标签文件的 YAML 内容应遵循以下结构：

type Tag = {
  label?: string; // 标签显示标签
  permalink?: string; // 标签 URL 路径名段
  description?: string; // 标签页面中显示的标签描述
};

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

示例

tags.yml

releases:
  label: '产品发布'
  permalink: '/product-releases'
  description: '与产品发布相关的内容。'

# 部分标签定义也是有效的
announcements:
  label: '公告'

# 空标签定义也是有效的
# 其他属性将从键推断
emptyTag:

content.md

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

# 标题

内容

Authors File

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

根据惯例，插件将在博客内容文件夹（s）的根目录中查找 authors.yml 文件。

此文件可以包含 全局博客作者 的预定义列表。您可以通过 authors front matter 引用这些作者。

Types

提供的 authors 文件的内容应尊重以下形状：

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;
};

Example

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: jimarcey@gmail.com
  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
│
│ # 网站/博客的翻译
├── blog
│   ├── 2021-04-15-blog-post.md
│   └── 2021-05-15-blog-post.md
├── blog.json
│
│ # 作者文件的翻译
└── authors.yml