版本：2.4.0

博客

博客功能允许你可以即时部署一个功能完全的博客。

信息

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

Initial setup

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

Then, add an item link to your blog within docusaurus.config.js:

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

Adding posts

要发布博文，只需在 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. This blog is created with [**Docusaurus 2**](https://docusaurus.io/).

<!--truncate-->

This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.

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 list

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

Use the  marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above  will be part of the summary. 举个例子：

---
title: Truncation Example
---

All these will be part of the blog post summary.

Even this.

<!--truncate-->

But anything from here on down will not be.

Not this.

Or this.

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

博客侧边栏会展示近期的博客文章。 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. 这样就会导致内容宽度增加。 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 rather make it say "All posts":

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

Blog post date

Docusaurus will extract a YYYY-MM-DD date from a file/folder name such as YYYY-MM-DD-my-blog-post-title.md.

Example supported patterns

格式	示例
单文件	`2021-05-28-my-blog-post-title.md`
MDX 文件	`2021-05-28-my-blog-post-title.mdx`
Single folder + `index.md`	`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`
Nested folders + `index.md`	`2021/05/28/my-blog-post-title/index.md`
日期位于路径中间	`category/2021/05-28-my-blog-post-title.md`

日期会从路径中被分离出来，添加到 URL 路径的开头。

提示

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

这种命名规则不是强制的，你也可以用 Markdown 前言设置发布日期。由于前言使用的是 YAML 语法，支持日期标记，所以如果你需要更精细的发布日期，可以使用前言。比如，如果你在同一天发布了多个帖子，你可以根据时间点排列它们：

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

博客文章作者可以直接在前言中声明：

Single author
Multiple authors

my-blog-post.md
---
authors:
  name: Joel Marcey
  title: Docusaurus 1 合作创造者
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: [email protected]
---

my-blog-post.md
---
authors:
  - name: Joel Marcey
    title: Docusaurus 1 合作创造者
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
    email: [email protected]
  - name: Sébastien Lorber
    title: Docusaurus 维护者
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
---

提示

这个选项最适合上手，或者填写临时，不常规供稿的作者。

信息

Prefer using the authors front matter, but the legacy author_* front matter remains supported:

my-blog-post.md
---
author: Joel Marcey
author_title: Docusaurus 1 合作创造者
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---

Global authors

对于规律供稿的博客文章作者来说，在每篇博文中都维护一份作者信息会很麻烦。

可以用一个配置文件，将这些作者全局声明：

website/blog/authors.yml
jmarcey:
  name: Joel Marcey
  title: Docusaurus 1 合作创造者
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: [email protected]

slorber:
  name: Sébastien Lorber
  title: Docusaurus 维护者
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png

提示

Use the authorsMapPath plugin option to configure the path. JSON 格式也支持。

在博文的前言，你可以引用在全局配置文件中声明的作者：

Single author
Multiple authors

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

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

你可以大部分时候使用全局作者，但仍然使用内联作者：

my-blog-post.md
---
authors:
  - jmarcey
  - slorber
  - name: 内联作者名
    title: 内联作者头衔
    url: https://github.com/inlineAuthor
    image_url: https://github.com/inlineAuthor
---

Local override of global authors

你可以在每篇博文中修改一些全局作者数据：

my-blog-post.md
---
authors:
  - key: jmarcey
    title: Joel Marcey 的新头衔
  - key: slorber
    name: Sébastien Lorber 的新名字
---

Localize the author's configuration file

配置文件可以被本地化，只需要创建一个本地化的复制版：

website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml

作者，不论是通过前言声明，还是通过作者映射表声明，都至少需要有姓名或头像中的一个。如果一篇帖子的所有作者都没有名字，Docusaurus 会紧密地显示他们的头像。 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 会根据每篇博文的字数生成一个估计阅读时间。我们提供了一个定制化的选项。

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.

提示

用这个回调来满足你的所有自定义需要：

Per-post disabling
Passing options
Using custom algorithms

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

用法:

---
hide_reading_time: true
---

这一页不会再显示阅读时间统计了！

Pass options to the default reading time function:

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 100}}),
        },
      },
    ],
  ],
};

Use a custom implementation of reading time:

docusaurus.config.js
const myReadingTime = require('./myReadingTime');

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content}) => myReadingTime(content),
        },
      },
    ],
  ],
};

Feed

You can generate RSS / Atom / JSON feed by passing feedOptions. 默认会自动生成 RSS 及 Atom 订阅源。 To disable feed generation, set feedOptions.type to 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
    /** Allow control over the construction of BlogFeedItems */
    createFeedItems?: (params: {
      blogPosts: BlogPost[];
      siteConfig: DocusaurusConfig;
      outDir: string;
      defaultCreateFeedItems: (params: {
        blogPosts: BlogPost[];
        siteConfig: DocusaurusConfig;
        outDir: string;
      }) => Promise<BlogFeedItem[]>;
    }) => Promise<BlogFeedItem[]>;
  };
};

示例用法：

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          feedOptions: {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
            createFeedItems: async (params) => {
              const {blogPosts, defaultCreateFeedItems, ...rest} = params;
              return defaultCreateFeedItems({
                // keep only the 10 most recent blog posts in the feed
                blogPosts: blogPosts.filter((item, index) => index < 10),
                ...rest,
              });
            },
          },
        },
      },
    ],
  ],
};

订阅源会位于：

RSS
Atom
JSON

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

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

https://example.com/blog/feed.json

Advanced topics

Blog-only mode

你的 Docusaurus 站点可以没有专门编写的首页，而是将博文列表设置为首页。 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 */
        },
      },
    ],
  ],
};

注意

Don't forget to delete the existing homepage at ./src/pages/index.js or else there will be two files mapping to the same route!

提示

Docusaurus 中还存在「仅文档模式」。 Read Docs-only mode for detailed instructions or a more elaborate explanation of routeBasePath.

Multiple blogs

默认情况下，经典主题假设一个网站只有一个博客，所以只有一个博客插件实例。如果你想在同一个站点上部署多个博客，也可以做到！ You can add another blog by specifying another blog plugin in the plugins option for docusaurus.config.js.

Set the routeBasePath to the URL route that you want your second blog to be accessed on. Note that the routeBasePath here has to be different from the first blog or else there could be a collision of paths! Also, set path to the path to the directory containing your second blog's entries.

As documented for multi-instance plugins, you need to assign a unique ID to the plugins.

docusaurus.config.js
module.exports = {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        /**
         * Required for any multi-instance plugin
         */
        id: 'second-blog',
        /**
         * URL route for the blog section of your site.
         * *DO NOT* include a trailing slash.
         */
        routeBasePath: 'my-second-blog',
        /**
         * Path to data on filesystem relative to site dir.
         */
        path: './my-second-blog',
      },
    ],
  ],
};

As an example, we host a second blog here.

博客

Initial setup​

Adding posts​

Blog list​

Blog sidebar​

Blog post date​

Blog post authors​

Inline authors​

Global authors​

Reading time​

Feed​

Advanced topics​

Blog-only mode​

Multiple blogs​