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

博客

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:

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

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; // 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.