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

博客

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

信息

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

初始设置

To set up your site's blog, start by creating a blog directory.

然后,在 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 上的首篇博文。

下方是一系列内容。

The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see the API documentation.

博客列表

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

在博文中使用 <!--truncate--> 来标记文章摘要。 <!--truncate--> 以上的内容均将成为摘要。 举个例子:

---
title: Truncation Example
---

All these will be part of the blog post summary.

甚至包括这一行。

<!--truncate-->

但这一行和这一行下方的内容将不会被截取。

这行不会。

这行也不会。

每个博客列表页面默认显示10篇博文,但你可以在插件配置中通过 postsPerPage 选项控制分页。 如果你设置了 postsPerPage: 'ALL',博文列表将不会被分页,所有博文都会显示在第一个页面上。 You can also add a meta description to the blog list page for better SEO:

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

博客侧边栏

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

你还可以通过 blogSidebarTitle 选项修改侧边栏的标题。 For example, if you have set blogSidebarCount: 'ALL', instead of the default "Recent posts", you may rather make it say "All posts":

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

Blog post date

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

支持的文件名格式示例:
Pattern示例
Single file2021-05-28-my-blog-post-title.md
MDX file2021-05-28-my-blog-post-title.mdx
Single folder + index.md2021-05-28-my-blog-post-title/index.md
Folder named by date2021-05-28/my-blog-post-title.md
Nested folders by date2021/05/28/my-blog-post-title.md
Partially nested folders by date2021/05-28-my-blog-post-title.md
Nested folders + index.md2021/05/28/my-blog-post-title/index.md
Date in the middle of pathcategory/2021/05-28-my-blog-post-title.md

The date will be excised from the path and appended to the beginning of the URL slug.

tip

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

This naming convention is optional, and you can also provide the date as front matter. Since the front matter follows YAML syntax where the datetime notation is supported, you can use front matter if you need more fine-grained publish dates. For example, if you have multiple posts published on the same day, you can order them according to the time of the day:

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

Blog post authors

Use the authors front matter field to declare blog post authors. An author should have at least a name or an image_url. Docusaurus uses information like url, email, and title, but any other information is allowed.

Inline authors

Blog post authors can be declared directly inside the front matter:

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
email: [email protected]
---
tip

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

信息

Prefer using the authors front matter, but the legacy author_* front matter 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 to 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
email: [email protected]

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 front matter, 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

An author, either declared through front matter or through the authors map, needs to have a name or an avatar, or both. If all authors of a post don't have names, Docusaurus will display their avatars compactly. See this test post for the effect.

Feed generation

RSS feeds require the author's email to be set for the author to appear in the feed.

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!

订阅源

You can generate RSS / Atom / JSON feed by passing feedOptions. 默认情况下将自动生成 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; // possible values: 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.`,
},
},
},
],
],
};

The feeds can be found at:

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

进阶议题

仅博客模式

You can run your Docusaurus 2 site without a dedicated landing page and instead have your blog's post list page as the index page. Set the routeBasePath to be '/' to serve the blog through the root route example.com/ instead of the subroute example.com/blog/.

docusaurus.config.js
module.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 */
},
},
],
],
};
caution

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

tip

There's also a "Docs-only mode" for those who only want to use the docs. Read Docs-only mode for detailed instructions or a more elaborate explanation of routeBasePath.

多个博客

默认情况下,经典主题假设一个网站仅有一个博客,故仅有一个博客插件实例。 若您想在单一站点上部署多个博客,这也可以! 您可以在 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',
},
],
],
};

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