跳到主要内容
版本:2.1.0

📦 plugin-content-blog

Docusaurus 的默认博客插件,提供了博客功能。

部分功能仅生产环境可用

订阅源功能通过提取构建输出实现,仅在生产环境中可用。

安装流程​

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

如果你已经安装了 @docusaurus/preset-classic,就不需要安装这个包了。

你可以通过预设选项配置这个插件。

配置​

接受的字段:

参数类型默认值描述
pathstring'blog'博客内容目录的文件系统路径,相对于站点目录。
editUrlstring | EditUrlFnundefined编辑文档的基础 URL。 最终的 URL 会按照 editUrl + relativePostPath 计算。 使用函数可以允许你更精细地控制每一个文件。 完全忽略这个变量就会禁用编辑链接。
editLocalizedFilesbooleanfalse编辑 URL 会指向本地化的文件,而不是原始的未翻译文件。 如果 editUrl 是一个函数,会完全忽略此选项。
blogTitlestring'Blog'用于增进 SEO 的博客页面标题。
blogDescriptionstring'Blog'用于增进 SEO 的博客页面元描述。
blogSidebarCountnumber | 'ALL'5在博客侧边栏中展示的博文项目数量。 'ALL' 会显示所有博文;0 会禁用侧边栏。
blogSidebarTitlestring'Recent posts'博客侧边栏的标题。
routeBasePathstring'blog'站点博客部分的 URL 前缀。 不要包含末尾斜杠。 / 会把博客放在根路径。
tagsBasePathstring'tags'博客标签部分的 URL 前缀。 会被添加到 routeBasePath 后面。 不要包含末尾斜杠。
archiveBasePathstring | null'archive'博客归档部分的 URL 前缀。 会被添加到 routeBasePath 后面。 不要包含末尾斜杠。 null 会禁止生成博客归档。
includestring[]['**/*.{md,mdx}']相对于内容路径的 glob 模式列表,匹配到的 Markdown 文件会被构建。
excludestring[]见示例配置Glob 模式列表,匹配到的 Markdown 文件会被排除。 在 include 选项的基础上进一步细调。
postsPerPagenumber | 'ALL'10每个博文列表页面显示的博文数量。 'ALL' 会让所有博文都展示在一个列表页上。
blogListComponentstring'@theme/BlogListPage'博客列表页的根组件。
blogPostComponentstring'@theme/BlogPostPage'每个博文页面的根组件。
blogTagsListComponentstring'@theme/BlogTagsListPage'标签列表页的根组件。
blogTagsPostsComponentstring'@theme/BlogTagsPostsPage'「包含某标签的所有博文」页面的根组件。
blogArchiveComponentstring'@theme/BlogArchivePage'博客归档页的根组件。
remarkPluginsany[][]传递给 MDX 的 Remark 插件。
rehypePluginsany[][]传递给 MDX 的 Rehype 插件。
beforeDefaultRemarkPluginsany[][]在 Docusaurus 默认 Remark 插件之前传递给 MDX 的自定义 Remark 插件。
beforeDefaultRehypePluginsany[][]在 Docusaurus 默认 Rehype 插件之前传递给 MDX 的自定义 Rehype 插件。
truncateMarkerRegExp/<!--\s*(truncate)\s*-->/标明摘要结束处的标记。
showReadingTimebooleantrue在博文上显示估计阅读时间。
readingTimeReadingTimeFn默认阅读时间用于自定义显示的阅读时间数字的回调。
authorsMapPathstring'authors.yml'作者记录表的文件路径,相对于博客内容目录。
feedOptions见下文{type: ['rss', 'atom']}博客订阅源。
feedOptions.typeFeedType | FeedType[] | 'all' | null必填要生成的订阅源类型。 null 会禁用订阅源生成。
feedOptions.titlestringsiteConfig.title订阅源的标题。
feedOptions.descriptionstring`${siteConfig.title} Blog`订阅源的描述。
feedOptions.copyrightstringundefined版权信息。
feedOptions.languagestring(所有可选值请见文档)undefined订阅源的语言元数据。
sortPosts'descending' | 'ascending' 'descending'决定博文排序的方向。

类型​

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

示例配置​

你可以通过预设选项或插件选项来配置这个插件。

提示

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

如果你使用预设,你可以通过预设选项配置这个插件:

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
path: 'blog',
// 一般使用场景:字符串 editUrl
// editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
// 高级使用场景:函数 editUrl
editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
`https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
editLocalizedFiles: false,
blogTitle: '博客标题',
blogDescription: '博客',
blogSidebarCount: 5,
blogSidebarTitle: '我们的所有博文',
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('remark-math')],
rehypePlugins: [],
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
truncateMarker: /<!--\s*(truncate)\s*-->/,
showReadingTime: true,
feedOptions: {
type: '',
title: '',
description: '',
copyright: '',
language: undefined,
},
},
},
],
],
};

Markdown 前言​

Markdown 文档可以使用以下前言元数据字段。前言的两端应用 --- 包裹。

接受的字段:

参数类型默认值描述
authorsAuthorsundefined博文作者列表(或者唯一作者)。 更多阐释可以参见 authors 指南。 即使文章只有一个作者,也推荐用 authors 而不是 author_* 字段。
authorstringundefined⚠️ 推荐使用 authors。 博文作者的名字。
author_urlstringundefined⚠️ 推荐使用 authors。 作者名字链接指向的 URL。 可以是 GitHub、Twitter、Facebook 个人主页,等等。
author_image_urlstringundefined⚠️ 推荐使用 authors。 作者头像图片的 URL。
author_titlestringundefined⚠️ 推荐使用 authors。 作者的描述。
titlestringMarkdown 标题博文的标题。
datestring文件名或文件创建时间博文的创建时间。 如果未给定,会从文件或文件夹名称中提取,例如:2021-04-15-blog-post.mdx、2021-04-15-blog-post/index.mdx、2021/04/15/blog-post.mdx。 如果也没有,会使用 Markdown 文件的创建时间。
tagsTag[]undefined一个列表,由字符串或者包含 label 和 permalink 字符串字段的对象构成,用于提供博文标签。
draftbooleanfalse一个布尔值,表明博文处于未完成状态。 博文草稿只会在开发模式下显示。
hide_table_of_contentsbooleanfalse是否隐藏右侧的文档目录。
toc_min_heading_levelnumber2目录中显示的最小标题层级。 必须介于 2 到 6 之间,并且小于等于最大值。
toc_max_heading_levelnumber3目录中显示的最大标题层级。 必须介于 2 和 6。
keywordsstring[]undefined关键词元标签,会变成 <head> 中的 <meta name="keywords" content="keyword1,keyword2,..."/>,被搜索引擎使用。
descriptionstringMarkdown 正文的第一行文档的描述信息,会生成 <head> 中被搜索引擎读取的 <meta name="description" content="..."/> 和 <meta property="og:description" content="..."/> 。
imagestringundefined显示文档链接时所用的缩略图或封面。
slugstring文件路径自定义博文的 URL (/<routeBasePath>/<slug>)。 支持多种形式: slug: my-blog-post、slug: /my/path/to/blog/post、slug: /。
type Tag = string | {label: string; permalink: string};

// 每个作者键名都引用了插件的全局 authors.yml 文件中的一个作者
type AuthorKey = string;

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

// 前言的 authors 字段允许各种可能的形状
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

示例:

---
title: 欢迎来到 Docusaurus v2
authors:
- slorber
- yangshun
- name: Joel Marcey
title: Docusaurus 1 合作创造者
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
tags: [hello, docusaurus-v2]
description: 这是我在 Docusaurus 2 上的首篇博文。
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

一篇 Markdown 博文

i18n​

请先阅读 i18n 简介。

翻译文件位置​

  • 基础路径:website/i18n/[语言]/docusaurus-plugin-content-blog
  • 多实例路径:website/i18n/[语言]/docusaurus-plugin-content-blog-[插件 ID]
  • JSON 文件:由 docusaurus write-translations 提取
  • Markdown 文件:website/i18n/[语言]/docusaurus-plugin-content-blog

文件系统结构示例​

website/i18n/[语言]/docusaurus-plugin-content-blog
│
│ # website/blog 的翻译
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # 会被渲染的插件选项的翻译
└── options.json