版本：2.1.0

博客

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

信息

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: '博客', position: 'left'}, // 或 position: 'right'
      ],
    },
  },
};

新建帖子

要发布博文，只需在 blog 目录中创建一个 Markdown 文件。

比如创建一个 website/blog/2019-09-05-hello-docusaurus-v2.md：

website/blog/2019-09-05-hello-docusaurus-v2.md
---
title: 欢迎来到 Docusaurus v2
description: 这是我关于 Docusaurus 2 的第一篇博文。
slug: welcome-docusaurus-v2
authors:
  - name: Joel Marcey
    title: Docusaurus 1 合作创造者
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
  - name: Sébastien Lorber
    title: Docusaurus 维护者
    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
---

欢迎来到本博客。 此博客使用 [**Docusaurus 2**](https://docusaurus.io/) 搭建。

<!--truncate-->

This is my first post on Docusaurus 2.

下方是一系列内容。

前言可以用来给你的博文添加更多元数据，比如作者信息，但 Docusaurus 能够自己推断所有必要的元数据，不需要前言。 For all possible fields, see the API documentation.

博文列表

博客的首页（默认为 /blog ）是博客列表页，会集中展示所有的博客文章。

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: 摘要示例
---

这些都会变成博文摘要。

甚至包括这一行。

<!--truncate-->

But anything from here on down will not be.

这行不会。

这行也不会。

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

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

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

你还可以通过 blogSidebarTitle 选项修改侧边栏的标题。比如如果设置了blogSidebarCount: 'ALL'，那么你可能想让侧边栏的标题为「所有文章」，而不是「近期文章」。

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

博客发布日期

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

支持的文件名格式示例

格式	示例
单文件	`2021-05-28-my-blog-post-title.md`
MDX 文件	`2021-05-28-my-blog-post-title.mdx`
单个文件夹 + `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`
嵌套文件夹 + `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
---

博客文章作者

用 author 前言字段声明博客文章作者。每个作者应该至少有 name 或 image_url 两个属性之一。 Docusaurus 还会使用 url、email、title 等信息，但任何其他信息都允许存在。

内联作者

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

单作者
多作者

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

提示

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

信息

建议使用 authors 前言，但以前的 author_* 类型的前言字段仍然支持：

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

全局作者

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

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

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

提示

用 authorsMapPath 插件选项设置文件路径。 JSON 格式也支持。

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

单作者
多作者

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

my-blog-post.md
---
authors: [jmarcey, slorber]
---

信息

authors 系统非常灵活，可以适应更高级的使用案例：

混合内联作者和全局作者

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

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

局部覆盖全局作者信息

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

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

将作者配置文件本地化

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

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

作者，不论是通过前言声明，还是通过作者映射表声明，都至少需要有姓名或头像中的一个。如果一篇帖子的所有作者都没有名字，Docusaurus 会紧密地显示他们的头像。在这篇测试帖子这里看看效果。

生成订阅源

RSS 要求作者设置了 email 才能出现在订阅源中。

阅读时间

Docusaurus 会根据每篇博文的字数生成一个估计阅读时间。我们提供了一个定制化的选项。

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          showReadingTime: true, // 如果设置为 false，「x 分钟阅读」的文字就不会显示
          readingTime: ({content, frontMatter, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 300}}),
        },
      },
    ],
  ],
};

readingTime 回调会收到三个参数：博客内容文本字符串，键值对形式的前言，以及默认的阅读时间函数。它会返回一个以分钟计的数字，或者返回 undefined（在此页上隐藏阅读时间）。

默认阅读时间可以接受额外的选项：一个数字 wordsPerminute（默认：300），以及一个接受字符串返回布尔值的函数 wordBound。如果传递给 wordBound 的字符串应当是一个词边界（默认为空格、制表符、换行），函数应返回 true。

提示

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

在某些帖子上隐藏时间
传递参数
使用自定义算法

在某一页上隐藏阅读时间：

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

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

把选项传递给默认阅读时间函数：

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

使用自定义的阅读时间算法实现：

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

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

订阅源

你可以通过 feedOptions 参数来生成 RSS / Atom / JSON 订阅源。默认会自动生成 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; // 可取的值：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.`,
          },
        },
      },
    ],
  ],
};

订阅源会位于：

RSS
Atom
JSON

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

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

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

进阶主题

仅博客模式

你的 Docusaurus 站点可以没有专门编写的首页，而是将博文列表设置为首页。把 routeBasePath 设置为 '/'，这样博客就会被放置在根路由 example.com/ 而不是子路由 example.com/blog/ 上。

docusaurus.config.js
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // 可选：禁用文档插件
        blog: {
          routeBasePath: '/', // 把博客放在站点根部
          /* 其他博客选项 */
        },
      },
    ],
  ],
};

注意

别忘记在这之后删除 ./src/pages/index.js 处的默认首页，否则两个文件都会映射到相同的路径！

提示

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

多个博客

默认情况下，经典主题假设一个网站只有一个博客，所以只有一个博客插件实例。如果你想在同一个站点上部署多个博客，也可以做到！你可以在 docusaurus.config.js 的 plugins 选项中添加另一个博客插件。

用 routeBasePath 为第二个博客设置 URL 路径前缀。要注意，这个 routeBasePath 必须与第一个博客的路由不同，否则会导致路径冲突！此外，请把 path 设置为包含你的第二个博客内容的文件目录路径。

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',
      {
        /**
         * 多实例插件必填。
         */
        id: 'second-blog',
        /**
         * 你的网站上博客的 URL 路由。
         * *请务必不要*添加末尾斜杠。
         */
        routeBasePath: 'my-second-blog',
        /**
         * 相对于站点目录的文件系统路径。
         */
        path: './my-second-blog',
      },
    ],
  ],
};

我们在这里建立了第二个博客作为示例。

博客

初始设置​

新建帖子​

博文列表​

博客侧边栏​

博客发布日期​

博客文章作者​

内联作者​

全局作者​

阅读时间​

订阅源​

进阶主题​

仅博客模式​

多个博客​