Version: 3.5.1

📦 plugin-content-blog

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

¥Provides the Blog feature and is the default blog plugin for Docusaurus.

部分功能仅限量产

饲料特性通过提取构建输出来工作，并且仅在生产中有效。

¥The feed feature works by extracting the build output, and is only active in production.

安装

¥Installation

npm
Yarn
pnpm

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

yarn add @docusaurus/plugin-content-blog

pnpm add @docusaurus/plugin-content-blog

提示

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

¥If you use the preset @docusaurus/preset-classic, you don't need to install this plugin as a dependency.

你可以通过预设选项.conf 配置该插件。

¥You can configure this plugin through the preset options.

配置

¥Configuration

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
`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 的插件。
`rehypePlugins`	`any[]`	`[]`	Rehype 插件传递给 MDX。
`rehypePlugins`	`any[]`	`[]`	传递给 MDX 的 Recma 插件。
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	自定义 Remark 插件在默认 Docusaurus Remark 插件之前传递到 MDX。
`beforeDefaultRehypePlugins`	`any[]`	`[]`	自定义 Rehype 插件在默认 Docusaurus Rehype 插件之前传递到 MDX。
`truncateMarker`	`RegExp`	`/<!--\struncate\s-->/` \| `\{\/\\struncate\s\\/\}/`	截断标记以标记摘要结束处。
`showReadingTime`	`boolean`	`true`	显示博客文章的预计阅读时间。
`readingTime`	`ReadingTimeFn`	默认阅读时间	用于自定义显示的阅读时间数的回调。
`authorsMapPath`	`string`	`'authors.yml'`	作者映射文件的路径，相对于博客内容目录。
`feedOptions`	见下文	`{type: ['rss', 'atom']}`	博客提要。
`feedOptions.type`	`FeedType \| FeedType[] \| 'all' \| null`	必需的	要生成的 feed 类型。使用 `null` 禁用生成。
`feedOptions.createFeedItems`	`CreateFeedItemsFn \| undefined`	`undefined`	一个可选函数，可用于转换和/或过滤提要中的项目。
`feedOptions.limit`	`number \| null \| false`	`20`	将提要限制为指定数量的帖子，所有条目为 `false` 或 `null`。默认为 `20`。
`feedOptions.title`	`string`	`siteConfig.title`	提要的标题。
`feedOptions.description`	`string`	`$\{siteConfig.title} Blog`	提要的描述。
`feedOptions.copyright`	`string`	`undefined`	版权信息。
`feedOptions.xslt`	`boolean \| FeedXSLTOptions`	`undefined`	版权信息。
`feedOptions.language`	`string`（有关可能的值，请参阅 documentation）	`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;
  wordBound: (char: string) => boolean;
};

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

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

`FeedType`

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

`FeedXSLTOptions`

允许设置博客 XML 提要的样式，以便浏览器使用 XSLT 很好地渲染它们。

¥Permits to style the blog XML feeds so that browsers render them nicely with XSLT.

使用 true 让博客使用其内置的 .xsl 和 .css 文件来设置博客提要的样式

¥Use true to let the blog use its built-in .xsl and .css files to style the blog feed
使用假值 (undefined | null | false) 禁用该功能

¥Use a falsy value (undefined | null | false) to disable the feature
使用 string 提供相对于博客内容文件夹的自定义 .xsl 文件的文件路径。按照惯例，你必须提供具有完全相同名称的 .css 文件。

¥Use a string to provide a file path to a custom .xsl file relative to the blog content folder. By convention, you must provide a .css file with the exact same name.

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

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

¥You can configure this plugin through preset options or plugin options.

提示

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

¥Most Docusaurus users configure this plugin through the preset options.

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

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 前言

¥Markdown front matter

Markdown 文档可以使用以下 Markdown 头条新闻元数据字段，两侧用 --- 行括起来。

¥Markdown documents can use the following Markdown front matter metadata fields, enclosed by a line --- on either side.

接受的字段：

¥Accepted fields:

名称	类型	默认	描述
`authors`	`Authors`	`undefined`	博客文章作者（或唯一作者）列表。阅读 `authors` 指南以获得更多解释。即使对于单一作者的博客文章，也更喜欢 `authors` 而不是 `author_*` 前事项字段。
`author`	`string`	`undefined`	⚠️ 更喜欢使用 `authors`。博客文章作者的名称。
`author_url`	`string`	`undefined`	⚠️ 更喜欢使用 `authors`。作者名称将链接到的 URL。这可以是 GitHub、Twitter、Facebook 个人资料 URL 等。
`author_image_url`	`string`	`undefined`	⚠️ 更喜欢使用 `authors`。作者缩略图的 URL。
`author_title`	`string`	`undefined`	⚠️ 更喜欢使用 `authors`。作者的描述。
`title`	`string`	Markdown 标题	博客文章标题。
`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.yml`）的键的引用
`draft`	`boolean`	`false`	博客文章草稿仅在开发期间可用。
`unlisted`	`boolean`	`false`	未列出的博客文章将在开发和生产中提供。它们在生产中将是 "hidden"，未编入索引，从站点地图中排除，并且只能由具有直接链接的用户访问。
`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,..."/>`，被搜索引擎使用。
`description`	`string`	第一行 Markdown 内容	你的文档的描述，将成为 `<head>` 中的 `<meta name="description" content="..."/>` 和 `<meta property="og:description" content="..."/>`，供搜索引擎使用。
`image`	`string`	`undefined`	将用作 `<head>` 中的 `<meta property="og:image" content="..."/>` 的封面或缩略图，增强社交媒体和消息平台上的链接预览。
`slug`	`string`	文件路径	允许自定义博客文章 URL (`/<routeBasePath>/<slug>`)。支持多种模式：`slug: my-blog-post`、`slug: /my/path/to/blog/post`、子弹：`/`。
`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") 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)[];

示例：

¥Example:

---
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 File

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

¥Use the tags plugin option to configure the path of a YAML tags file.

按照惯例，插件将在你的内容文件夹的根目录中查找 tags.yml 文件。

¥By convention, the plugin will look for a tags.yml file at the root of your content folder(s).

此文件可以包含预定义标签列表。借助 tags 前言，你可以在 Markdown 文件中通过它们的键引用这些标签。

¥This file can contain a list of predefined tags. You can reference these tags by their keys in Markdown files thanks to the tags front matter.

保持标签一致

使用标签文件，你可以确保你的标签使用在整个插件内容集中保持一致。使用 onInlineTags: 'throw' 插件选项来强制这种一致性并防止使用动态声明的内联标签。

¥Using a tags file, you can ensure that your tags usage is consistent across your plugin content set. Use the onInlineTags: 'throw' plugin option to enforce this consistency and prevent usage of inline tags declared on the fly.

类型

¥Types

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

¥The YAML content of the provided tags file should respect the following shape:

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

示例

¥Example

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 File

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

¥Use the authors plugin option to configure the path of a YAML authors file.

按照惯例，插件将在你的博客内容文件夹的根目录中查找 authors.yml 文件。

¥By convention, the plugin will look for a authors.yml file at the root of your blog content folder(s).

此文件可以包含预定义的全局博客作者列表。借助 authors 前言，你可以通过 Markdown 文件中的键引用这些作者。

¥This file can contain a list of predefined global blog authors. You can reference these authors by their keys in Markdown files thanks to the authors front matter.

类型

¥Types

提供的作者文件的 YAML 内容应遵循以下形状：

¥The YAML content of the provided authors file should respect the following shape:

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

首先阅读国际化介绍。

¥Read the i18n introduction first.

翻译文件位置

¥Translation files location

基本路径：website/i18n/[locale]/docusaurus-plugin-content-blog

¥Base path: website/i18n/[locale]/docusaurus-plugin-content-blog
多实例路径：website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]

¥Multi-instance path: website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]
JSON 文件：用 docusaurus write-translations 提取

¥JSON files: extracted with docusaurus write-translations
Markdown 文件：website/i18n/[locale]/docusaurus-plugin-content-blog

¥Markdown files: website/i18n/[locale]/docusaurus-plugin-content-blog

文件系统结构示例

¥Example file-system structure

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

安装​

配置​

类型​

EditUrlFn​

ReadingTimeFn​

FeedType​

FeedXSLTOptions​

CreateFeedItemsFn​

ProcessBlogPostsFn​

配置示例​

Markdown 前言​

标签文件​

类型​

示例​

作者文件​

类型​

示例​

国际化​

翻译文件位置​

文件系统结构示例​

安装

配置

类型

`EditUrlFn`

`ReadingTimeFn`

`FeedType`

`FeedXSLTOptions`

`CreateFeedItemsFn`

`ProcessBlogPostsFn`

配置示例

Markdown 前言

标签文件

类型

示例

作者文件

类型

示例

国际化

翻译文件位置

文件系统结构示例