跳到主要内容
版本:2.0.1

博客

博客功能允许你可以即时部署一个功能完全的博客。

信息

阅读博客插件 API 参考文档了解配置选项的完整列表。

初始设置

要为你的站点设置博客,请先创建 blog 目录。

然后,在 docusaurus.config.js 内创建指向你的博客的链接项。

docusaurus.config.js
module.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: '博客', 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: 欢迎来到 Docusaurus v2
description: 这是我关于 Docusaurus 2 的第一篇博文。
slug: welcome-docusaurus-v2
authors:
- name: Joel Marcey
title: Docusaurus 1 合作创造者
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
- name: Sébastien Lorber
title: Docusaurus 维护者
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
---

欢迎来到本博客。 此博客使用 [**Docusaurus 2**](https://docusaurus.io/) 搭建。

<!--truncate-->

这是我在 Docusaurus 2 上的首篇博文。

下方是一系列内容。

前言可以用来给你的博文添加更多元数据,比如作者信息,但 Docusaurus 能够自己推断所有必要的元数据,不需要前言。 要了解所有可用的字段,可以访问 API 文档

博文列表

博客的首页(默认为 /blog )是博客列表页,会集中展示所有的博客文章。

在博文中用 <!--truncate--> 来标记文章摘要。摘要部分会在总览所有博文时显示。 <!--truncate--> 以上的内容都会成为摘要。 举个例子:

---
title: 摘要示例
---

这些都会变成博文摘要。

甚至包括这一行。

<!--truncate-->

但这一行和这一行下面的内容就不会了。

这行不会。

这行也不会。

每页博客列表默认显示 10 篇博文,但你可以在插件配置中通过 postsPerPage 选项控制分页。 如果你设置了 postsPerPage: 'ALL',博文列表将不会被分页,所有博文都会显示在第一页上。 你也可以在博文列表页添加元描述以进行搜索引擎优化:

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus 博客!',
blogDescription: '这是个用 Docusaurus 搭建的博客!',
postsPerPage: 'ALL',
},
},
],
],
};

博客侧边栏

博客侧边栏会展示近期的博客文章。 默认会显示 5 篇,你可以通过博客插件的 blogSidebarCount 选项来自定义显示的数量。 如果设置 blogSidebarCount: 0,则会直接隐藏侧边栏,包括侧边栏的容器, 这样就会导致内容宽度增加。 如果设置 blogSidebarCount: 'ALL',那么所有的文章都会显示。

你还可以通过 blogSidebarTitle 选项修改侧边栏的标题。 比如如果设置了blogSidebarCount: 'ALL',那么你可能想让侧边栏的标题为「所有文章」,而不是「近期文章」。

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogSidebarTitle: '全部博文',
blogSidebarCount: 'ALL',
},
},
],
],
};

博客发布日期

Docusaurus 会从目录/文件名中,解析出 YYYY-MM-DD 格式的发布日期,例如 YYYY-MM-DD-my-blog-post-title.md.

支持的文件名格式示例
格式示例
单文件2021-05-28-my-blog-post-title.md
MDX 文件2021-05-28-my-blog-post-title.mdx
单个文件夹 + index.md2021-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.md2021/05/28/my-blog-post-title/index.md
日期位于路径中间category/2021/05-28-my-blog-post-title.md

日期会从路径中被分离出来,添加到 URL 路径的开头。

提示

使用文件夹的形式,可以方便地把博客所需要的图片等资源和 Markdown 文档放在一起。

这种命名规则不是强制的,你也可以用 Markdown 前言设置发布日期。 由于前言使用的是 YAML 语法,支持日期标记,所以如果你需要更精细的发布日期,可以使用前言。 比如,如果你在同一天发布了多个帖子,你可以根据时间点排列它们:

earlier-post.md
---
date: 2021-09-13T10:00
---
later-post.md
---
date: 2021-09-13T18:00
---

博客文章作者

author 前言字段声明博客文章作者。 每个作者应该至少有 nameimage_url 两个属性之一。 Docusaurus 还会使用 urlemailtitle 等信息,但任何其他信息都允许存在。

内联作者

博客文章作者可以直接在前言中声明:

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]
---
提示

这个选项最适合上手,或者填写临时,不常规供稿的作者。

信息

建议使用 authors 前言,但以前的 author_* 类型的前言字段仍然支持:

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.yml
jmarcey:
name: Joel Marcey
title: Docusaurus 1 合作创造者
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: [email protected]

slorber:
name: Sébastien Lorber
title: Docusaurus 维护者
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
提示

authorsMapPath 插件选项设置文件路径。 JSON 格式也支持。

在博文的前言,你可以引用在全局配置文件中声明的作者:

my-blog-post.md
---
authors: jmarcey
---
信息

authors 系统非常灵活,可以适应更高级的使用案例:

混合内联作者和全局作者

你可以大部分时候使用全局作者,但仍然使用内联作者:

my-blog-post.md
---
authors:
- jmarcey
- slorber
- name: 内联作者名
title: 内联作者头衔
url: https://github.com/inlineAuthor
image_url: https://github.com/inlineAuthor
---
局部覆盖全局作者信息

你可以在每篇博文中修改一些全局作者数据:

my-blog-post.md
---
authors:
- key: jmarcey
title: Joel Marcey 的新头衔
- key: slorber
name: Sébastien Lorber 的新名字
---
将作者配置文件本地化

配置文件可以被本地化,只需要创建一个本地化的复制版:

website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml

作者,不论是通过前言声明,还是通过作者映射表声明,都至少需要有姓名或头像中的一个。 如果一篇帖子的所有作者都没有名字,Docusaurus 会紧密地显示他们的头像。 在这篇测试帖子这里看看效果。

生成订阅源

RSS 要求作者设置了 email 才能出现在订阅源中。

阅读时间

Docusaurus 会根据每篇博文的字数生成一个估计阅读时间。 我们提供了一个定制化的选项。

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true, // 如果设置为 false,「x 分钟阅读」的文字就不会显示
readingTime: ({content, frontMatter, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 300}}),
},
},
],
],
};

readingTime 回调会收到三个参数:博客内容文本字符串, 键值对形式的前言,以及默认的阅读时间函数。 它会返回一个以分钟计的数字,或者返回 undefined(在此页上隐藏阅读时间)。

默认阅读时间可以接受额外的选项: 一个数字 wordsPerminute(默认:300),以及一个接受字符串返回布尔值的函数 wordBound。 如果传递给 wordBound 的字符串应当是一个词边界(默认为空格、制表符、换行),函数应返回 true

提示

用这个回调来满足你的所有自定义需要:

在某一页上隐藏阅读时间:

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true,
readingTime: ({content, frontMatter, defaultReadingTime}) =>
frontMatter.hide_reading_time
? undefined
: defaultReadingTime({content}),
},
},
],
],
};

用法:

---
hide_reading_time: true
---

这一页不会再显示阅读时间统计了!

订阅源

你可以通过 feedOptions 参数来生成 RSS / Atom / JSON 订阅源。 默认会自动生成 RSS 及 Atom 订阅源。 要关闭订阅源生成,请将 feedOptions.type 设置为 null

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

type BlogOptions = {
feedOptions?: {
type?: FeedType | 'all' | FeedType[] | null;
title?: string;
description?: string;
copyright: string;
language?: string; // 可取的值:http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
};
};

示例用法:

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
feedOptions: {
type: 'all',
copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
},
},
},
],
],
};

订阅源会位于:

https://example.com/blog/rss.xml

进阶主题

仅博客模式

你的 Docusaurus 站点可以没有专门编写的首页,而是将博文列表设置为首页。 把 routeBasePath 设置为 '/',这样博客就会被放置在根路由 example.com/ 而不是子路由 example.com/blog/ 上。

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false, // 可选:禁用文档插件
blog: {
routeBasePath: '/', // 把博客放在站点根部
/* 其他博客选项 */
},
},
],
],
};
注意

别忘记在这之后删除 ./src/pages/index.js 处的默认首页,否则两个文件都会映射到相同的路径!

提示

Docusaurus 中还存在「仅文档模式」。 阅读仅文档模式了解 routeBasePath详情。

多个博客

默认情况下,经典主题假设一个网站只有一个博客,所以只有一个博客插件实例。 如果你想在同一个站点上部署多个博客,也可以做到! 你可以在 docusaurus.config.jsplugins 选项中添加另一个博客插件。

routeBasePath 为第二个博客设置 URL 路径前缀。 要注意,这个 routeBasePath 必须与第一个博客的路由不同,否则会导致路径冲突! 此外,请把 path 设置为包含你的第二个博客内容的文件目录路径。

多实例插件中所述,你需要给每个插件分配唯一的 ID。

docusaurus.config.js
module.exports = {
// ...
plugins: [
[
'@docusaurus/plugin-content-blog',
{
/**
* 多实例插件必填。
*/
id: 'second-blog',
/**
* 你的网站上博客的 URL 路由。
* *请务必不要*添加末尾斜杠。
*/
routeBasePath: 'my-second-blog',
/**
* 相对于站点目录的文件系统路径。
*/
path: './my-second-blog',
},
],
],
};

我们在这里建立了第二个博客作为示例。