博客

¥Blog

博客功能使你能够立即部署功能齐全的博客。

¥The blog feature enables you to deploy a full-featured blog in no time.

信息

检查 博客插件 API 参考文档 以获得详尽的选项列表。

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

初始设置

¥Initial setup

要设置站点的博客，请首先创建 blog 目录。

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

然后，在 docusaurus.config.js 内添加指向你博客的项目链接：

¥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

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

¥To publish in the blog, create a Markdown file within the blog directory.

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

¥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 2**](https://docusaurus.nodejs.cn/).

<!-- truncate -->

This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.

头条新闻 对于向你的博客文章添加更多元数据（例如作者信息）非常有用，但 Docusaurus 将能够在没有前面内容的情况下推断出所有必要的元数据。对于所有可能的字段，请参阅 API 文档。

¥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

博客的索引页（默认位于 /blog）是博客列表页，集中显示所有博客文章。

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

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

¥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. Note that the portion above the truncate marker must be standalone renderable Markdown. For example:

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.

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

¥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'，分页将被禁用，所有帖子将显示在第一页。你还可以向博客列表页面添加元描述以获得更好的搜索引擎优化：

¥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. You can also add a meta description to the blog list page for better SEO:

docusaurus.config.js

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

博客侧边栏

¥Blog sidebar

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

¥The blog sidebar displays recent blog posts. 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. This will increase the width of the main container. Specially, if you have set blogSidebarCount: 'ALL', all posts will be displayed.

你还可以使用 blogSidebarTitle 选项更改侧边栏标题文本。例如，如果你设置了 blogSidebarCount: 'ALL'，而不是默认的 "最近的帖子"，你可能宁愿将其设置为 "所有帖子"：

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

¥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. This enables you to easily group blog posts by year, by month, or to use a flat structure.

Supported date extraction patterns

图案	示例
单文件	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 可以使用上述任何命名模式从帖子中提取日期。建议选择一种模式并将其应用于所有帖子以避免混淆。

¥Docusaurus can extract the date from the posts using any of the naming patterns above. It is advisable to choose one pattern and apply it to all posts to avoid confusion.

提示

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

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

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

¥This naming convention is optional, and you can also provide the date as front matter. Since the front matter follows YAML syntax where the datetime notation is supported, you can use front matter if you need more fine-grained publish dates. For example, if you have multiple posts published on the same day, you can order them according to the time of the day:

earlier-post.md

---
date: 2021-09-13T10:00
---

later-post.md

---
date: 2021-09-13T18:00
---

博客文章作者

¥Blog post authors

使用 authors Front Matter 字段声明博客文章作者。作者应该至少有 name 或 image_url。Docusaurus 使用 url、email 和 title 等信息，但允许任何其他信息。

¥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

博客文章作者可以直接在前面的内容中声明：

¥Blog post authors can be declared directly inside the front matter:

Single author

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: jimarcey@gmail.com
  socials:
    x: joelmarcey
    github: JoelMarcey
---

Multiple authors

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: jimarcey@gmail.com
    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
---

提示

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

¥This option works best to get started, or for casual, irregular authors.

信息

更喜欢使用 authors 前面的内容，但旧版 author_* 前面的内容仍然受支持：

¥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

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

¥For regular blog post authors, it can be tedious to maintain authors' information inlined in each blog post.

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

¥It is possible to declare those authors globally in a configuration file:

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: jimarcey@gmail.com
  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。

¥Use the authorsMapPath plugin option to configure the path. JSON is also supported.

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

¥In blog posts front matter, you can reference the authors declared in the global configuration file:

Single author

my-blog-post.md

---
authors: jmarcey
---

Multiple authors

my-blog-post.md

---
authors: [jmarcey, slorber]
---

信息

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

¥The authors system is very flexible and can suit more advanced use-case:

Mix inline authors and global authors

大多数时候你可以使用全局作者，并且仍然使用内联作者：

¥You can use global authors most of the time, and still use inline 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

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

¥You can customize the global author's data on per-blog-post basis:

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

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

¥The configuration file can be localized, just create a localized copy of it at:

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

作者，无论是通过前言还是通过作者地图声明，都需要有名称或头像，或两者兼而有之。如果帖子的所有作者都没有名字，Docusaurus 将紧凑地显示他们的头像。效果见 这个测试帖。

¥An author, either declared through front matter or through the authors map, needs to have a name or an avatar, or both. If all authors of a post don't have names, Docusaurus will display their avatars compactly. See this test post for the effect.

饲料生成

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

¥RSS feeds require the author's email to be set for the author to appear in the feed.

作者页面

¥Authors pages

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

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

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

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

• 每个作者的专用作者页面 (example) 列出了他们贡献的所有博客文章

  ¥a dedicated author page for each author (example) listing all the blog posts they contributed to

• 作者索引页 (example) 列出了所有这些作者，按他们在 authors.yml 中出现的顺序

  ¥an authors index page (example) listing all these authors, in the order they appear in authors.yml

关于内联作者

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

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

可以内联定义标签，或引用在 tags file 中声明的预定义标签（可选，通常为 blog/tags.yml）。

¥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 引用了在 blog/tags.yml 中声明的预定义标签键

  ¥docusaurus references a predefined tag key declared in blog/tags.yml

• Releases 是一个内联标签，因为它在 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'

阅读时间

¥Reading time

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

¥Docusaurus generates a reading time estimation for each blog post based on word count. We provide an option to customize this.

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（禁用此页面的阅读时间）。

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

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

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

提示

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

¥Use the callback for all your customization needs:

Per-post disabling

禁用一页上的阅读时间：

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

Passing options

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

¥Pass options to the default reading time function:

docusaurus.config.js

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

Using custom algorithms

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

¥Use a custom implementation of reading time:

docusaurus.config.js

import myReadingTime from './myReadingTime';

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

Feed

你可以通过传递 feedOptions 来生成 RSS / Atom / JSON feed。默认情况下，会生成 RSS 和 Atom 提要。要禁用 Feed 生成，请将 feedOptions.type 设置为 null。

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

RSS

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

Atom

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

JSON

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

高级主题

¥Advanced topics

纯博客模式

¥Blog-only mode

你可以在没有专用登录页面的情况下运行 Docusaurus 网站，而是将博客的帖子列表页面作为索引页面。将 routeBasePath 设置为 '/'，通过根路由 example.com/ 而不是子路由 example.com/blog/ 为博客提供服务。

¥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 */
        },
      },
    ],
  ],
};

警告

不要忘记删除 ./src/pages/index.js 处现有的主页，否则会有两个文件映射到同一路由！

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

提示

对于那些只想使用文档的人来说，还有 "仅文档模式"。请阅读 仅文档模式 以获取详细说明或 routeBasePath 的更详细解释。

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

多个博客

¥Multiple blogs

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

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

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

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

根据 多实例插件 的记录，你需要为插件分配一个唯一的 ID。

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