跳到主要内容
版本：Canary 🚧

博客

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

信息

阅读Blog插件 API 参考文档了解配置选项的完整列表。

初始设置​

要为你的站点设置博客，请先创建 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: 文章帖子的标题
description: 文章帖子的描述
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
    socials:
      x: joelmarcey
      github: JoelMarcey
  - name: Sébastien Lorber
    title: Docusaurus maintainer
    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
---

Welcome to this blog. 此博客使用 [**Docusaurus 2**](https://docusaurus.io/) 搭建。

<!-- truncate -->

This is my first post on Docusaurus 2.

下方是一系列内容。

前言可以用来给你的博文添加更多元数据，比如作者信息，但 Docusaurus 能够自己推断所有必要的元数据，不需要前言。 要了解所有可用的字段，可以访问 API 文档。

博文列表​

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

在博文中用 <!--truncate--> 来标记文章摘要。摘要部分会在总览所有博文时显示。 任何<!--truncate--> 标记以上的内容都会成为摘要。 请注意，Truncate标记以上的部分必须是独立的、可渲染的Markdown。 举个例子：

website/blog/my-post.md
---
title: Markdown blog truncation example
---

All these will be part of the blog post summary.

<!-- truncate -->

But anything from here on down will not be.

For files using the .mdx extension, use a MDX comment {/* truncate */} instead:

website/blog/my-post.mdx
---
title: MDX blog truncation Example
---

All these will be part of the blog post summary.

{/* truncate */}

But anything from here on down will not be.

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

docusaurus.config.js
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogTitle: 'Docusaurus blog!',
          blogDescription: 'A Docusaurus powered blog!',
          postsPerPage: 'ALL',
        },
      },
    ],
  ],
};

博客侧边栏​

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

你也可以通过修改 blogSidebarTitle 的参数修改侧边栏的展示数量。 比如，如果你把 blogSidebarCount 的值改成了 'ALL' ，那么上一个值的默认值就便不是默认的 "Recent posts"，而应该是 "All posts"：

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

博客发布日期​

Docusaurus 将从许多模式（例如 YYYY-MM-DD-my-blog-post-title.md 或 YYYY/MM/DD/my-blog-post-title.md）中提取 YYYY-MM-DD 日期。 这使你能够轻松地按年、按月对博客文章进行分组，或使用扁平结构。 这使你能够轻松地按年、按月对博客文章进行分组，或使用扁平结构。

支持的日期提取模式
格式示例
单文件2021-05-28-my-blog-post-title.md
MDX 文件2021-05-28-my-blog-post-title.mdx
单个文件夹 + index.md2021-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.md2021/05/28/my-blog-post-title/index.md
日期位于路径中间category/2021/05-28-my-blog-post-title.md

此命名约定是可选的，你也可以提供日期作为前面的内容。 最好选择一种模式，并将其适用于所有文档，以避免混乱。

提示

Using a folder can be convenient to co-locate blog post images alongside the Markdown file.

此命名约定是可选的，你也可以提供日期作为前面的内容。 由于 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: Co-creator of Docusaurus 1
  url: https://github.com/JoelMarcey
  image_url: https://github.com/JoelMarcey.png
  email: [email protected]
  socials:
    x: joelmarcey
    github: JoelMarcey
---
提示

此选项最适合初学者或临时、不定期的作者。

信息

我们更建议使用 authors 属性，但旧版 author_* 属性仍然可以使用：

my-blog-post.md
---
author: Joel Marcey
author_title: Co-creator of 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: Co-creator of 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 maintainer
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png
  socials:
    x: sebastienlorber
    github: slorber
提示

请使用 authorsMapPath 插件选项来配置路径。 还同样支持JSON格式。

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

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

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
---
本地覆盖全局作者

你可以根据每个博客文章自定义全局作者数据：

my-blog-post.md
---
authors:
  - key: jmarcey
    title: Joel Marcey's new title
  - key: slorber
    name: Sébastien Lorber's new name
---
本地化作者的配置文件

配置文件可以本地化，只需在以下位置创建它的本地化副本：

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

作者，无论是通过Front Matter还是通过作者地图声明，都需要有名称或头像，或两者都有。 如果帖子的所有作者都没有名字，Docusaurus 将紧凑地显示他们的头像。 请参阅 这个测试帖子。

订阅源生成

RSS 订阅 要求设置作者的电子邮件以便作者出现在提要中。

Authors pages​

The authors pages feature is optional, and mainly useful for multi-author blogs.

You can activate it independently for each author by adding a page: true attribute to the global author configuration:

website/blog/authors.yml
slorber:
  name: Sébastien Lorber
  page: true # Turns the feature on - route will be /authors/slorber

jmarcey:
  name: Joel Marcey
  page:
    # Turns the feature on - route will be /authors/custom-author-url
    permalink: '/custom-author-url'

The blog plugin will now generate:

  • a dedicated author page for each author (example) listing all the blog posts they contributed to
  • an authors index page (example) listing all these authors, in the order they appear in authors.yml
About inline authors

Only global authors can activate this feature. Inline authors are not supported.

Blog post tags​

Tags are declared in the front matter and introduce another dimension of categorization.

It is possible to define tags inline, or to reference predefined tags declared in a tags file (optional, usually blog/tags.yml).

In the following example:

  • docusaurus references a predefined tag key declared in blog/tags.yml
  • Releases is an inline tag, because it does not exist in blog/tags.yml
blog/my-post.md
---
title: 'My blog post'
tags:
  - Releases
  - docusaurus
---

Content
blog/tags.yml
docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: 'Blog posts related to the Docusaurus framework'

阅读时间​

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

docusaurus.config.js
export default {
  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}}),
        },
      },
    ],
  ],
};

readingTime 回调接收三个参数： 博客内容文本作为字符串，前文作为字符串键及其值的记录，以及默认的阅读时间函数。 它返回一个数字（以分钟为单位的阅读时间）或 undefined（禁用此页面的阅读时间）。

默认读取时间可以接受附加选项：wordsPerMinute 作为数字（默认值：300），wordBound 作为从字符串到布尔值的函数。 如果传递给 wordBound 的字符串应该是单词绑定的（默认为空格、制表符和换行符），则该函数应返回 true。

提示

Use the callback for all your customization needs:

Disable reading time on one page:

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

Usage:

---
hide_reading_time: true
---

This page will no longer display the reading time stats!

订阅源​

You can generate RSS / Atom / JSON feed by passing feedOptions. By default, RSS and Atom feeds are generated. 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
    limit?: number | false | null; // defaults to 20
    // XSLT permits browsers to style and render nicely the feed XML files
    xslt?:
      | boolean
      | {
          //
          rss?: string | boolean;
          atom?: string | boolean;
        };
    // 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[]>;
  };
};

Example usage:

docusaurus.config.js
export default {
  // ...
  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,
              });
            },
          },
        },
      },
    ],
  ],
};

The feeds can be found at:

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

进阶主题​

仅博客模式​

You can run your Docusaurus site without a dedicated landing page and instead have your blog's post list page as the index page. 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
export default {
  // ...
  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!

警告

If you disable the docs plugin, don't forget to delete references to the docs plugin elsewhere in your configuration file. Notably, make sure to remove the docs-related navbar items.

提示

There's also a "Docs-only mode" for those who only want to use the docs. Read Docs-only mode for detailed instructions or a more elaborate explanation of routeBasePath.

多个博客​

By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! 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
export default {
  // ...
  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.