第1章 Docusaurus 2.x 博客功能配置与发布指南

版本：2.xBlog 博客功能让你可以快速搭建一个功能完整的博客。 infoBlog 插件的全部配置项，请查阅 Blog Plugin API Reference 文档。 初始设置 要搭建博客，先创建一个 blog 目录。 然后在 docusaurus.config.js 中为博客添加导航链接： docusaurus.config.jsmodule.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: 'Blog', position: 'left'}, // 或 position: 'right'
],
},
},
};
发布文章 要发布博文，只需在 blog 目录中创建一个 Markdown 文件。 例如，创建文件 website/blog/2019-09-05-hello-docusaurus-v2.md： website/blog/2019-09-05-hello-docusaurus-v2.md---
title: Welcome Docusaurus v2
description: This is my first post on Docusaurus 2.
slug: welcome-docusaurus-v2
authors:
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

Welcome to this blog. This blog is created with [Docusaurus 2](https://docusaurus.io/).



This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.
front matter 用于为文章补充元数据（如作者信息），但即使不写 front matter，Docusaurus 也能自动推断出所有必要的元数据。所有可用字段请参考 API 文档。 博客列表 博客的索引页（默认在 /blog）就是博客列表页，集中展示所有博文。 在博文中使用 标记，可以指定在列表页展示的摘要内容：标记之前的部分会作为摘要显示。注意，标记之前的内容必须是可独立渲染的 Markdown。例如： ---
title: Truncation Example
---

All these will be part of the blog post summary.

Even this.



But anything from here on down will not be.

Not this.

Or this.
默认情况下，博客列表页每页显示 10 篇文章，但可通过插件配置中的 postsPerPage 选项控制分页。将 postsPerPage 设为 'ALL' 时，分页功能会被禁用，所有文章将全部展示在首页。你还可添加 meta 描述以改善博客列表页的 SEO 效果： docusaurus.config.jsmodule.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 'ALL',
},
},
],
],
};
博客侧边栏 博客侧边栏会显示近期的博客文章。默认显示数量为 5 篇，但可通过插件配置中的 blogSidebarCount 选项进行自定义。将 blogSidebarCount 设为 0 时，侧边栏会被完全禁用，其容器也一并移除，从而加宽主内容区的显示宽度。另外，若将 blogSidebarCount 设为 'ALL'，则所有文章都会展示出来。 此外，你还能通过 blogSidebarTitle 选项修改侧边栏标题。例如，在 blogSidebarCount 设为 'ALL' 时，可将默认的 "Recent posts" 改为 "All posts"： docusaurus.config.jsmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogSidebarTitle: 'All posts',
blogSidebarCount: 'ALL',
},
},
],
],
};
博客文章日期 Docusaurus 会从文件名或文件夹名（如 `YYYY-MM-DD-my-blog-post-title.md`）中提取 `YYYY-MM-DD` 格式的日期。 支持的模式示例： - 单个文件：`2021-05-28-my-blog-post-title.md` - MDX 文件：`2021-05-28-my-blog-post-title.mdx` - 单个文件夹 + index.md：`2021-05-28-my-blog-post-title/index.md` - 以日期命名的文件夹：`2021-05-28/my-blog-post-title.md` - 按日期嵌套文件夹：`2021/05/28/my-blog-post-title.md` - 部分按日期嵌套文件夹：`2021/05-28-my-blog-post-title.md` - 嵌套文件夹 + index.md：`2021/05/28/my-blog-post-title/index.md` - 路径中间包含日期：`category/2021/05-28-my-blog-post-title.md` 日期会从路径中移除，并添加到 URL slug 的开头。 提示：使用文件夹可以方便地将博客文章图片与 Markdown 文件放在一起。 这种命名约定是可选的，你也可以通过 front matter 提供日期。由于 front matter 遵循支持日期时间标记的 YAML 语法，如果需要更精细的发布时间（例如同一天发布多篇文章并按时间排序），可以使用 front matter： earlier-post.md --- date: 2021-09-13T10:00 --- later-post.md --- date: 2021-09-13T18:00 --- 博客文章作者 使用 `authors` front matter 字段声明博客文章作者。每位作者至少需要包含名称或 `image_url`。Docusaurus 会利用 `url`、`email` 和 `title` 等信息，但也允许其他信息。 内联作者 可以直接在 front matter 中声明博客文章作者： 单作者 / 多作者 my-blog-post.md --- authors: name: Joel Marcey title: Docusaurus 1 联合创始人 url: https://github.com/JoelMarcey image_url: https://github.com/JoelMarcey.png email: [email protected] --- my-blog-post.md --- authors: - name: Joel Marcey title: Docusaurus 1 联合创始人 url: https://github.com/JoelMarcey image_url: https://github.com/JoelMarcey.png email: [email protected] - name: Sébastien Lorber title: Docusaurus 维护者 url: https://sebastienlorber.com image_url: https://github.com/slorber.png --- 提示：此选项适合快速上手，或作者较为随意、不固定的情况。 信息：建议优先使用 `authors` front matter 字段，但旧版的 `author_*` front matter 字段仍受支持： my-blog-post.md --- author: Joel Marcey author_title: Docusaurus 1 联合创始人 author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---
全局作者 对于经常撰写博客文章的作者来说，在每篇文章中内联维护作者信息会非常繁琐。你可以在一个配置文件中全局声明这些作者： website/blog/authors.ymljmarcey:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: [email protected]

slorber:
name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
提示：可以通过 authorsMapPath 插件选项来配置路径，也支持 JSON 格式。 在博客文章的 front matter 中，你可以引用全局配置文件中声明的作者： 单作者多作者my-blog-post.md---
authors: jmarcey
---
my-blog-post.md---
authors: [jmarcey, slorber]
--- 说明：作者系统非常灵活，可以满足更高级的使用场景： 混合使用内联作者和全局作者 大多数情况下你可以使用全局作者，同时仍然可以使用内联作者： my-blog-post.md---
authors:
- jmarcey
- slorber
- name: Inline Author name
title: Inline Author Title
url: https://github.com/inlineAuthor
image_url: https://github.com/inlineAuthor
---
局部覆盖全局作者 你可以针对单篇博客文章自定义全局作者的数据： my-blog-post.md---
authors:
- key: jmarcey
title: Joel Marcey's new title
- key: slorber
name: Sébastien Lorber's new name
---
本地化作者配置文件 配置文件支持本地化，只需在以下位置创建本地化副本： website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
作者（无论是通过 front matter 还是通过 authors map 声明的）必须提供 name 或头像，或两者皆有。如果某篇文章的所有作者都没有名字，Docusaurus 会以紧凑的方式展示他们的头像。效果参见这篇测试文章。 Feed 生成 RSS feed 要求设置作者的 email，作者才会出现在 feed 中。 阅读时长 Docusaurus 会基于字数为每篇博客文章估算阅读时长，并提供了自定义选项。 docusaurus.config.jsmodule.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true, // 设为 false 时，不显示“x 分钟阅读”
readingTime: ({content, frontMatter, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 300}}),
},
},
],
],
};
readingTime 回调接收三个参数：博客正文文本（字符串）、Front matter（字符串键值对记录）以及默认阅读时间函数。返回值是一个数字（以分钟为单位的阅读时间）或 undefined（为该页面禁用阅读时间）。 默认阅读时间函数支持传入额外选项：wordsPerMinute 为数字（默认值 300），wordBound 是一个从字符串到布尔值的函数。如果传入 wordBound 的字符串被判定为单词边界（默认包括空格、制表符和换行符），该函数应返回 true。 tip 利用该回调满足各种自定义需求： - 按文章禁用阅读时间 - 传入自定义选项 - 使用自定义算法 在一页面上禁用阅读时间： docusaurus.config.js module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true,
readingTime: ({content, frontMatter, defaultReadingTime}) =>
frontMatter.hide_reading_time
? undefined
: defaultReadingTime({content}),
},
},
],
],
};
Front matter 示例： ---
hide_reading_time: true
---

该页面将不再显示阅读时长统计。 向默认阅读时间函数传入选项： docusaurus.config.js module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 100}}),
},
},
],
],
};
使用自定义阅读时间算法： docusaurus.config.js const myReadingTime = require('./myReadingTime');

module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content}) => myReadingTime(content),
},
},
],
],
};
Feed 源 通过传入 feedOptions 即可生成 RSS / Atom / JSON Feed。默认情况下，会生成 RSS 和 Atom Feed。若要禁用 Feed 生成，将 feedOptions.type 设为 null。 type FeedType = 'rss' | 'atom' | 'json';

type BlogOptions = {
feedOptions?: {
type?: FeedType | 'all' | FeedType[] | null;
title?: string;
description?: string;
copyright: string;
language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
/ Allow control over the construction of BlogFeedItems */
createFeedItems?: (params: {
blogPosts: BlogPost[];
siteConfig: DocusaurusConfig;
outDir: string;
defaultCreateFeedItems: (params: {
blogPosts: BlogPost[];
siteConfig: DocusaurusConfig;
outDir: string;
}) => Promise;
}) => Promise;
};
};
使用示例： docusaurus.config.jsmodule.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
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,
});
},
},
},
},
],
],
};
Feed 可访问以下地址： RSSAtomJSONhttps://example.com/blog/rss.xml
https://example.com/blog/atom.xml
https://example.com/blog/feed.json
进阶主题​ 仅博客模式​ 你可以让 Docusaurus 2 网站不设置专属落地页，转而将博客的文章列表页作为首页。将 routeBasePath 设置为 '/'，即可通过根路径 example.com/ 访问博客，而非子路径 example.com/blog/。 docusaurus.config.jsmodule.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false, // Optional: disable the docs plugin
blog: {
routeBasePath: '/', // Serve the blog at the site's root
/* other blog options */
},
},
],
],
};
warning别忘了删除已有的首页文件 ./src/pages/index.js，否则会有两个文件映射到同一路由！ tip如果只想使用文档功能，还有"仅文档模式"可用。详细操作说明及 routeBasePath 的更多解释请参阅 Docs-only mode。 多个博客 默认情况下，classic 主题假定每个网站只有一个博客，因此只包含一个博客插件实例。如果你想在一个网站上放多个博客，也没问题！只需在 docusaurus.config.js 的 plugins 选项中添加另一个博客插件即可。 将 routeBasePath 设置为你希望第二个博客访问的 URL 路由。注意这里的 routeBasePath 必须与第一个博客不同，否则路径会冲突！同时，将 path 设置为第二个博客文章所在目录的路径。 如多实例插件的文档所述，你需要为插件分配一个唯一的 ID。 docusaurus.config.jsmodule.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/
* 任何多实例插件都必须设置
*/
id: 'second-blog',
/
* 博客部分的 URL 路由。
* *切勿*包含末尾斜杠。
*/
routeBasePath: 'my-second-blog',
/
* 相对于站点目录的数据路径。
*/
path: './my-second-blog',
},
],
],
};
举个例子，我们在这里托管了第二个博客。