博客

博客功能让你能够在短时间内快速部署一个功能齐全的博客。

信息

初始设置

要设置你网站的博客，首先创建一个 blog 目录。

然后，在 docusaurus.config.js 文件中为你博客的导航栏添加一个链接项：

docusaurus.config.js
export default {
  themeConfig: {
    // ...
    navbar: {
      items: [
        // ...
        {to: 'blog', label: '博客', position: 'left'}, // 或 position: 'right'
      ],
    },
  },
};

添加文章

要在博客中发布内容，请在 blog 目录下创建一个 Markdown 文件。

例如，在 website/blog/2019-09-05-hello-docusaurus.md 位置创建一个文件：

website/blog/2019-09-05-hello-docusaurus.md
---
title: 欢迎使用道格龙（Docusaurus）
description: 这是我在道格龙（Docusaurus）上的第一篇文章。
slug: welcome-docusaurus-v2
authors:
  - name: Joel Marcey
    title: 道格龙（Docusaurus）1 的联合创始人
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
    socials:
      x: joelmarcey
      github: JoelMarcey
  - name: Sébastien Lorber
    title: 道格龙（Docusaurus）维护者
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
    socials:
      x: sebastienlorber
      github: slorber
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

欢迎来到这个博客。本博客是使用 [**道格龙（Docusaurus）**](https://docusaurus.io/) 创建的。

<!-- truncate -->

这是我在道格龙（Docusaurus）上的第一篇文章。

接下来将有一大堆探索。

头部元数据（Front matter）对于为你的博客文章添加更多元数据（例如作者信息）非常有用，但即使没有 front matter，道格龙（Docusaurus）也能推断出所有必要的元数据。关于所有可能的字段，请参阅 API 文档。

博客列表

博客的索引页（默认为 /blog）是博客列表页，所有博客文章都会在这里集中展示。

在你的博客文章中使用  标记来表示在查看所有已发布的博客文章时将显示为摘要的内容。任何在  之上的内容都将成为摘要的一部分。请注意，截断标记以上的部分必须是可独立渲染的 Markdown。例如：

website/blog/my-post.md
---
title: Markdown 博客截断示例
---

所有这些内容都将成为博客文章摘要的一部分。

<!-- truncate -->

但从这里开始往下的任何内容都不会。

对于使用 .mdx 扩展名的文件，请改用 MDX 注释 {/* truncate */}：

website/blog/my-post.mdx
---
title: MDX 博客截断示例
---

所有这些内容都将成为博客文章摘要的一部分。

{/* truncate */}

但从这里开始往下的任何内容都不会。

默认情况下，每个博客列表页显示 10 篇文章，但你可以通过插件配置中的 postsPerPage 选项来控制分页。如果设置 postsPerPage: 'ALL'，分页将被禁用，所有文章都将显示在第一页。你还可以为博客列表页添加一个 meta description 以获得更好的 SEO 效果：

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogTitle: '道格龙（Docusaurus）博客！',
          blogDescription: '一个由道格龙（Docusaurus）驱动的博客！',
          postsPerPage: 'ALL',
        },
      },
    ],
  ],
};

博客侧边栏会显示最近的博客文章。默认显示的项目数量是 5 个，但你可以通过插件配置中的 blogSidebarCount 选项进行自定义。通过设置 blogSidebarCount: 0，侧边栏将被完全禁用，其容器也会被移除。这将增加主容器的宽度。特别地，如果你设置了 blogSidebarCount: 'ALL'，则会显示所有文章。

你还可以通过 blogSidebarTitle 选项更改侧边栏的标题文本。例如，如果你设置了 blogSidebarCount: 'ALL'，你可能希望将默认的"近期文章"更改为"所有文章"：

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogSidebarTitle: '所有文章',
          blogSidebarCount: 'ALL',
        },
      },
    ],
  ],
};

博客文章日期

道格龙（Docusaurus）会从多种模式中提取 YYYY-MM-DD 格式的日期，例如 YYYY-MM-DD-my-blog-post-title.md 或 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`

道格龙（Docusaurus）可以使用上述任何一种命名模式从文章中提取日期。建议选择一种模式并将其应用于所有文章，以避免混淆。

提示

使用文件夹可以方便地将博客文章的图片与 Markdown 文件放在一起。

这种命名约定是可选的，你也可以在 front matter 中提供日期。由于 front matter 遵循支持日期时间符号的 YAML 语法，因此如果你需要更精细的发布日期，可以使用 front matter。例如，如果你在同一天发布了多篇文章，可以根据一天中的不同时间对它们进行排序：

earlier-post.md
---
date: 2021-09-13T10:00
---

later-post.md
---
date: 2021-09-13T18:00
---

博客文章作者

使用 authors front matter 字段来声明博客文章的作者。一个作者至少需要一个 name 或一个 image_url。道格龙（Docusaurus）会使用诸如 url、email 和 title 这样的信息，但也允许包含任何其他信息。

内联作者

博客文章的作者可以直接在 front matter 中声明：

单个作者
多个作者

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]
  socials:
    x: joelmarcey
    github: JoelMarcey
---

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]
    socials:
      x: joelmarcey
      github: JoelMarcey
  - name: Sébastien Lorber
    title: 道格龙（Docusaurus）维护者
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
    socials:
      x: sebastienlorber
      github: slorber
---

提示

这个选项最适合用于快速入门，或用于非正式、不固定的作者。

信息

推荐使用 authors front matter，但旧版的 author_* front matter 仍然受支持：

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]
  socials:
    x: joelmarcey
    github: JoelMarcey

slorber:
  name: Sébastien Lorber
  title: 道格龙（Docusaurus）维护者
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png
  socials:
    x: sebastienlorber
    github: slorber

提示

使用 authorsMapPath 插件选项来配置路径。也支持 JSON 格式。

在博客文章的 front matter 中，你可以引用在全局配置文件中声明的作者：

单个作者
多个作者

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

一个作者，无论是通过 front matter 还是通过作者映射文件声明，都需要有一个名字或一个头像，或者两者兼有。如果一篇文章的所有作者都没有名字，道格龙（Docusaurus）将紧凑地显示他们的头像。效果可以参考这篇测试文章。

Feed 生成

RSS feeds 要求设置作者的电子邮件，以便作者能出现在 feed 中。

作者页面

作者页面功能是可选的，主要对多作者博客有用。

你可以通过在全局作者配置中为每个作者添加 page: true 属性来独立激活它：

website/blog/authors.yml
slorber:
  name: Sébastien Lorber
  page: true # 开启此功能 - 路由将是 /authors/slorber

jmarcey:
  name: Joel Marcey
  page:
    # 开启此功能 - 路由将是 /authors/custom-author-url
    permalink: '/custom-author-url'

现在，博客插件将生成：

为每位作者生成一个专属的作者页面（示例），列出他们贡献的所有博客文章
一个作者索引页面（示例），列出所有这些作者，顺序与他们在 authors.yml 中出现的顺序一致

关于内联作者

只有全局作者可以激活此功能。不支持内联作者。

博客文章标签

标签在 front matter 中声明，并引入了另一个维度的分类。

可以内联定义标签，或者引用在标签文件（可选，通常是 blog/tags.yml）中预定义的标签。

在以下示例中：

docusaurus 引用了在 blog/tags.yml 中声明的预定义标签键
Releases 是一个内联标签，因为它不存在于 blog/tags.yml 中

blog/my-post.md
---
title: '我的博客文章'
tags:
  - Releases
  - docusaurus
---

内容

blog/tags.yml
docusaurus:
  label: '道格龙（Docusaurus）'
  permalink: '/docusaurus'
  description: '与道格龙（Docusaurus）框架相关的博客文章'

阅读时间

道格龙（Docusaurus）会根据字数估算每篇博客文章的阅读时间。我们提供了一个选项来自定义此功能。

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          showReadingTime: true, // 设置为 false 时，将不显示"x 分钟阅读"
          readingTime: ({content, locale, frontMatter, defaultReadingTime}) =>
            defaultReadingTime({
              content,
              locale,
              options: {wordsPerMinute: 300},
            }),
        },
      },
    ],
  ],
};

readingTime 回调函数接收以下参数：

content：博客内容的字符串形式
frontMatter：front matter，作为字符串键及其值的记录
locale：当前道格龙（Docusaurus）网站的语言环境
defaultReadingTime：默认的内置阅读时间函数。它返回一个数字（以分钟为单位的阅读时间）或 undefined（禁用此页面的阅读时间）。

默认的阅读时间函数能够接受额外的选项：

wordsPerMinute，一个数字（默认：300）

提示

使用回调函数满足你所有的自定义需求：

单篇禁用
传递选项
使用自定义算法

在单个页面上禁用阅读时间：

docusaurus.config.js
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          showReadingTime: true,
          readingTime: ({content, locale, frontMatter, defaultReadingTime}) =>
            frontMatter.hide_reading_time
              ? undefined
              : defaultReadingTime({content, locale}),
        },
      },
    ],
  ],
};

用法：

---
hide_reading_time: true
---

此页面将不再显示阅读时间统计信息！

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

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

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

docusaurus.config.js
import myReadingTime from './myReadingTime';

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, locale}) => myReadingTime(content, locale),
        },
      },
    ],
  ],
};

Feed

你可以通过传递 feedOptions 来生成 RSS / Atom / JSON feed。默认情况下，会生成 RSS 和 Atom feed。要禁用 feed 生成，请将 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
    limit?: number | false | null; // 默认为 20
    // XSLT 允许浏览器更好地样式化和渲染 feed XML 文件
    xslt?:
      | boolean
      | {
          //
          rss?: string | boolean;
          atom?: string | boolean;
        };
    // 允许控制 BlogFeedItems 的构建
    createFeedItems?: (params: {
      blogPosts: BlogPost[];
      siteConfig: DocusaurusConfig;
      outDir: string;
      defaultCreateFeedItems: (params: {
        blogPosts: BlogPost[];
        siteConfig: DocusaurusConfig;
        outDir: string;
      }) => Promise<BlogFeedItem[]>;
    }) => Promise<BlogFeedItem[]>;
  };
};

用法示例：

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          feedOptions: {
            type: 'all',
            copyright: `版权所有 © ${new Date().getFullYear()} Facebook, Inc.`,
            createFeedItems: async (params) => {
              const {blogPosts, defaultCreateFeedItems, ...rest} = params;
              return defaultCreateFeedItems({
                // 在 feed 中只保留最近的 10 篇博客文章
                blogPosts: blogPosts.filter((item, index) => index < 10),
                ...rest,
              });
            },
          },
        },
      },
    ],
  ],
};

Feed 可以在以下地址找到：

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
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false, // 可选：禁用文档插件
        blog: {
          routeBasePath: '/', // 在网站根目录提供博客服务
          /* 其他博客选项 */
        },
      },
    ],
  ],
};

注意

别忘了删除 ./src/pages/index.js 中已有的主页，否则会有两个文件映射到同一个路由！

注意

如果你禁用了文档插件，别忘了在你的配置文件中删除其他地方对文档插件的引用。特别是，要确保移除与文档相关的导航栏项目。

提示

还有一个"纯文档模式"，适用于那些只想使用文档功能的用户。请阅读纯文档模式以获取详细说明或对 routeBasePath 更详尽的解释。

多个博客

默认情况下，经典主题假设每个网站只有一个博客，因此只包含一个博客插件的实例。如果你想在一个网站上有多个博客，也是可以的！你可以通过在 docusaurus.config.js 的 plugins 选项中指定另一个博客插件来添加另一个博客。

将 routeBasePath 设置为你希望第二个博客访问的 URL 路由。请注意，这里的 routeBasePath 必须与第一个博客的不同，否则可能会发生路径冲突！此外，将 path 设置为包含你第二个博客条目的目录路径。

正如多实例插件文档中所述，你需要为插件分配一个唯一的 ID。

docusaurus.config.js
export default {
  // ...
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        /**
         * 对于任何多实例插件都是必需的
         */
        id: 'second-blog',
        /**
         * 你网站博客部分的 URL 路由。
         * *不要*包含结尾的斜杠。
         */
        routeBasePath: 'my-second-blog',
        /**
         * 文件系统中相对于网站目录的数据路径。
         */
        path: './my-second-blog',
      },
    ],
  ],
};

作为一个例子，我们在这里托管了第二个博客这里。

初始设置​

添加文章​

博客列表​

博客侧边栏​

博客文章日期​

博客文章作者​

内联作者​

全局作者​

作者页面​

博客文章标签​

阅读时间​

Feed​

高级主题​

纯博客模式​

多个博客​