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

博客

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

信息

阅读博客插件 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 will extract a YYYY-MM-DD date from a file/folder name such as YYYY-MM-DD-my-blog-post-title.md.

This naming convention is optional, and you can provide the date as FrontMatter.

Example supported patterns
  • 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

Using a folder can be convenient to co-locate blog post images alongside the Markdown file.

The only required field in the front matter is title; however, we provide options to add more metadata to your blog post, for example, author information. For all possible fields, see the API documentation.

Blog list

The blog's index page (by default, it is at /blog) is the blog list page, where all blog posts are collectively displayed.

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

---
title: 摘要示例
---
这些都将作为博文摘要。

甚至包括这一行。

<!--truncate-->

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

这行不会。

这行也不会。

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

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

博客侧边栏

The blog sidebar displays recent blog posts. The default number of items shown is 5, but you can customize with the blogSidebarCount option in the plugin configuration. By setting blogSidebarCount: 0, the sidebar will be completely disabled, with the container removed as well. This will increase the width of the main container. Specially, if you have set blogSidebarCount: 'ALL', all posts will be displayed.

You can also alter the sidebar heading text with the blogSidebarTitle option. For example, if you have set blogSidebarCount: 'ALL', instead of the default "Recent posts", you may would rather make it say "All posts":

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

订阅源

您可以通过传递 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',
},
],
],
};

As an example, we host a second blog here.