📦 plugin-content-blog

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

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

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

安装

npm

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

Yarn

yarn add @docusaurus/plugin-content-blog

pnpm

pnpm 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	默认的阅读时间	一个回调函数，用于自定义显示的阅读时间数字。
authorsMapPath	string	'authors.yml'	作者映射文件的路径，相对于博客内容目录。
feedOptions	See below	{type: ['rss', 'atom']}	博客 feed。
feedOptions.type	FeedType | FeedType[] | 'all' | null	Required	要生成的 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	版权信息。
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;
  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 feed 进行样式化，以便浏览器使用 XSLT 美观地呈现它们。

• 使用 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 前置 matter

Markdown 文档可以使用以下 Markdown 前置 matter 元数据字段，两侧用 --- 行包围。

接受的字段

名称	类型	默认值	描述
authors	作者	undefined	博客文章作者（或唯一作者）的列表。阅读 authors 指南 以了解更多解释。即使是单作者博客文章，也优先使用 authors 而不是 author_* 前置 matter 字段。
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。作者描述。
标题	string	Markdown 标题	博客文章标题。
日期	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）的键的引用。
草稿	boolean	false	草稿博客文章仅在开发期间可用。
未列出	boolean	false	未列出的博客文章在开发和生产环境中都可用。它们将在生产环境中“隐藏”，不会被索引，不包含在站点地图中，并且只能通过拥有直接链接的用户访问。
hide_table_of_contents	boolean	false	是否隐藏右侧的目录。
toc_min_heading_level	编号	2	目录中显示的最小标题级别。必须介于 2 和 6 之间，并且小于或等于最大值。
toc_max_heading_level	编号	3	目录中显示的最大标题级别。必须介于 2 和 6 之间。
关键词	string[]	undefined	关键词元标签，将成为 <head> 中的 <meta name="keywords" content="keyword1,keyword2,..."/>，供搜索引擎使用。
描述	string	Markdown 内容的第一行	文档的描述，将成为 <head> 中的 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/>，供搜索引擎使用。
图片	string	undefined	封面或缩略图，将用作 <head> 中的 <meta property="og:image" content="..."/>，增强社交媒体和消息平台上的链接预览。
别名	string	文件路径	允许自定义博客文章 URL（/<routeBasePath>/<slug>）。支持多种模式：slug: my-blog-post、slug: /my/path/to/blog/post、slug: /。
最后更新	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)[];

示例

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