跳到主要内容
版本：3.8.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
export default {
  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.md:

website/blog/2019-09-05-hello-docusaurus.md
---
title: Welcome Docusaurus
description: This is my first post on Docusaurus.
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. This blog is created with [**Docusaurus**](https://docusaurus.io/).

<!-- truncate -->

This is my first post on Docusaurus.

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 <!--truncate--> marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above <!--truncate--> will be part of the summary. 请注意，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.

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
export default {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogTitle: 'Docusaurus blog!',
          blogDescription: 'A Docusaurus powered blog!',
          postsPerPage: 'ALL',
        },
      },
    ],
  ],
};

Blog sidebar​

博客侧边栏会展示近期的博客文章。 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
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogSidebarTitle: 'All posts',
          blogSidebarCount: 'ALL',
        },
      },
    ],
  ],
};

Blog post date​

Docusaurus will extract a YYYY-MM-DD date from many patterns such as YYYY-MM-DD-my-blog-post-title.md or YYYY/MM/DD/my-blog-post-title.md. 这使你能够轻松地按年、按月对博客文章进行分组，或使用扁平结构。

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

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

提示

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

此命名约定是可选的，你也可以提供日期作为前面的内容。 由于 Front Matter 遵循支持日期时间表示法的 YAML 语法，因此如果你需要更细粒度的发布日期，可以使用 Front Matter。 例如，如果你在同一天发布了多个帖子，你可以根据一天中的时间对它们进行排序：

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​

博客文章作者可以直接在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
---
提示

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

信息

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

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

Global authors​

对于普通博客的文章作者们来说，维护每篇博客文章中内嵌的作者信息可能很枯燥乏味。

所以，我们可以在配置文件中全局声明这些作者：

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

Use the authorsMapPath plugin option to configure the path. 还同样支持JSON格式。

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

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

在大多数时候你可以使用全局作者，并且在极小部分需要的时候仍然使用内联作者：

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

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

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

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

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

作者，无论是通过Front Matter还是通过作者地图声明，都需要有名称或头像，或两者都有。 如果帖子的所有作者都没有名字，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.

作者页面​

作者页面是可选的，主要用于多作者的博客站点。

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 # 启用这一功能 - 路由将会是 /authors/slorber

jmarcey:
  name: Joel Marcey
  page:
    # 启用这一功能 - 路由将会是 /authors/custom-author-url
    permalink: '/custom-author-url'

博客插件现在将生成：

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

博客帖子标签​

Tags 已经在前言中被声明，引入了另一个分类层面。

可以定义内联标记，也可以引用标记文件(可选，通常为blog/tags.yml)中声明的预定义标记。

下面的示例：

  • docusaurus 引用了一个在 blog/tags.yml 中声明的预定义标签键
  • Releases 是一个内联标签，因为它不存在于blog/tags.yml
blog/my-post.md
---
title: 'My blog post'
tags:
  - Releases
  - docusaurus
---

Content
blog/tags.yml
docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: '与 Docusaurus 框架相关的博客文章'

Reading time​

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, locale, frontMatter, defaultReadingTime}) =>
            defaultReadingTime({
              content,
              locale,
              options: {wordsPerMinute: 300},
            }),
        },
      },
    ],
  ],
};

The readingTime callback receives the following parameters:

  • content: the blog content text as a string
  • frontMatter: the front matter as a record of string keys and their values
  • locale: the locale of the current Docusaurus site
  • defaultReadingTime: the default built-in 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)
提示

使用回调来满足您的所有自定义需要：

Disable reading time on one page:

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

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

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
    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[]>;
  };
};

示例用法：

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

订阅源会位于：

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

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

警告

如果您禁用了 docs 插件，请不要忘记删除配置文件中对 docs 插件的引用。 值得注意的是，请务必移除与 docs 相关的导航栏项目。

提示

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