跳转至主内容
Version: 2.0.0-beta.9

博客

博客功能使你可以即时部署一个功能丰富的博客。

信息

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

初始设置

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

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

docusaurus.config.js
module.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: 'Blog', position: 'left'}, // 或 position: 'right'
],
},
},
};

添加文章

要发布博文,在 blog 目录中创建一个 Markdown 文件。

For example, create a file at 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. 此博客使用 [**Docusaurus 2**](https://docusaurus.io/) 搭建。

<!--truncate-->

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

下方是一系列内容。
note

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

这种命名规则不是强制的,你也可以从 Markdown 文档开头的配置(FrontMatter)中设置发布日期。

支持的文件名格式示例:
  • 2021-05-28-my-blog-post-title.md
  • 2021-05-28-my-blog-post-title.mdx
  • 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
  • 2021/05/28/my-blog-post-title/index.md
  • ...
tip

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

在 Markdown 文档的配置项中,只有 title 属性是必填项;不过 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',
},
},
],
],
};

Blog post authors

Use the authors FrontMatter field to declare blog post authors.

Inline authors

Blog post authors can be declared directly inside the FrontMatter:

my-blog-post.md
---
authors:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
---
tip

This option works best to get started, or for casual, irregular authors.

信息

Prefer usage of the authors FrontMatter, but the legacy author_* FrontMatter remains supported:

my-blog-post.md
---
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---

Global authors

For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post.

It is possible declare those authors globally in a configuration file:

website/blog/authors.yml
jmarcey:
name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png

slorber:
name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
tip

Use the authorsMapPath plugin option to configure the path. JSON is also supported.

In blog posts FrontMatter, you can reference the authors declared in the global configuration file:

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

The authors system is very flexible and can suit more advanced use-case:

Mix inline authors and global authors
You can use global authors most of the time, and still use inline authors:
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
---
Local override of global authors

You can customize the global author's data on per-blog-post basis:

my-blog-post.md
---
authors:
- key: jmarcey
title: Joel Marcey's new title
- key: slorber
name: Sébastien Lorber's new name
---
Localize the author's configuration file

The configuration file can be localized, just create a localized copy of it at:

website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml

Reading time

Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.

docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true, // When set to false, the "x min read" won't be shown
readingTime: ({content, frontMatter, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 300}}),
},
},
],
],
};

The readingTime callback receives three parameters: the blog content text as a string, front matter as a record of string keys and their values, and the default reading time function. It returns a number (reading time in minutes) or undefined (disable reading time for this page).

The default reading time is able to accept additional options: wordsPerMinute as a number (default: 300), and wordBound as a function from string to boolean. If the string passed to wordBound should be a word bound (spaces, tabs, and line breaks by default), the function should return true.

tip

Use the callback for all your customization needs:

Disable reading time on one page:

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

Usage:

---
hide_reading_time: true
---

This page will no longer display the reading time stats!

订阅源

您可以通过传递 feedOptions 参数来生成 RSS/Atom 订阅源。 默认情况下将自动生成 RSS 及 Atom 订阅源。 要关闭订阅源生成,请将 feedOptions.type 设置为 null

type BlogOptions = {
feedOptions?: {
type?: 'rss' | 'atom' | 'all' | 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: `版权所有 © ${new Date().getFullYear()} Facebook, Inc.`,
},
},
},
],
],
};

访问订阅源:

您的 RSS 订阅源位于:

https://{您的域名}/blog/rss.xml

Atom 源:

https://{您的域名}/blog/atom.xml

进阶议题

仅博客模式

您可将去除您 Docusaurus 2 站点上的着陆页,并将博文列表设置为首页。 将 routeBasePath 设置为 '/' 以指定为根目录。

docusaurus.config.js
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
docs: false,
blog: {
path: './blog',
routeBasePath: '/', // 将其设置为 '/'。
},
},
],
],
};
caution

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

多个博客

默认情况下,经典主题假设一个网站仅有一个博客,故仅有一个博客插件实例。 若您想在单一站点上部署多个博客,这也可以! 您可以在 docusaurus.config.js 中的 plugins 选项中指定其他博客插件来添加博客。

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',
},
],
],
};

点击这里来查看第二博客示例。