博客

The blog feature enables you to deploy in no time a full-featured blog.

信息

Check the Blog Plugin API Reference documentation for an exhaustive list of options.

初始设置

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

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

docusaurus.config.js

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

添加文章

To publish in the blog, create a Markdown file within the blog directory.

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 v2description: This is my first post on Docusaurus 2.slug: welcome-docusaurus-v2authors:  - 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.pngtags: [hello, docusaurus-v2]image: https://i.imgur.com/mErPwqL.pnghide_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-->
但这一行和这一行下方的内容将不会被截取。
这行不会。
这行也不会。

By default, 10 posts are shown on each blog list page, but you can control pagination with the postsPerPage option in the plugin configuration. If you set postsPerPage: 'ALL', pagination will be disabled and all posts will be displayed on the first page. 您也可以在博文列表页添加元描述以来进行搜索引擎优化：

docusaurus.config.js

module.exports = {  // ...  presets: [    [      '@docusaurus/preset-classic',      {        blog: {          blogTitle: 'Docusaurus blog!',          blogDescription: 'A Docusaurus powered blog!',          postsPerPage: 'ALL',        },      },    ],  ],};

Blog sidebar

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: 'All posts',          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:

Single author

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---

Multiple authors

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  - name: Sébastien Lorber    title: Docusaurus maintainer    url: https://sebastienlorber.com    image_url: https://github.com/slorber.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 Marceyauthor_title: Co-creator of Docusaurus 1author_url: https://github.com/JoelMarceyauthor_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:

Single author

my-blog-post.md

---authors: jmarcey---

Multiple authors

my-blog-post.md

---authors: [jmarcey, slorber]---

信息

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; // 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: `版权所有 © ${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.