Version: 3.7.0

博客

博客功能使您能够快速部署一个功能齐全的博客。

info

初始设置

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

然后，在docusaurus.config.js中添加一个项目链接到你的博客：

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

添加帖子

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

例如，在 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.io/).

<!-- truncate -->

This is my first post on Docusaurus 2.

A whole bunch of exploration to follow.

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

博客列表

博客的索引页面（默认情况下，它在/blog）是博客列表页面，所有博客文章都在这里集中显示。

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

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

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'，分页将被禁用，所有文章将显示在第一页上。您还可以为博客列表页面添加元描述以改善SEO：

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'，而不是默认的“最近文章”，你可能更希望它显示为“所有文章”：

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

博客发布日期

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

Supported date extraction patterns

Pattern	Example
Single file	`2021-05-28-my-blog-post-title.md`
MDX file	`2021-05-28-my-blog-post-title.mdx`
Single folder + `index.md`	`2021-05-28-my-blog-post-title/index.md`
Folder named by date	`2021-05-28/my-blog-post-title.md`
Nested folders by date	`2021/05/28/my-blog-post-title.md`
Partially nested folders by date	`2021/05-28-my-blog-post-title.md`
Nested folders + `index.md`	`2021/05/28/my-blog-post-title/index.md`
Date in the middle of path	`category/2021/05-28-my-blog-post-title.md`

Docusaurus 可以从使用上述任何命名模式的帖子中提取日期。建议选择一个模式并将其应用于所有帖子，以避免混淆。

tip

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

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

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

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

博客文章作者

使用authors前置字段来声明博客文章的作者。一个作者应该至少有一个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
---

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
  - name: Sébastien Lorber
    title: Docusaurus maintainer
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
    socials:
      x: sebastienlorber
      github: slorber
---

tip

此选项最适合初学者，或者偶尔、不规律写作的作者。

info

建议使用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

tip

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

在博客文章的前言部分，您可以引用全局配置文件中声明的作者：

单一作者
多位作者

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

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

info

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

作者，无论是通过前言声明还是通过作者映射声明，都需要有一个名字或一个头像，或者两者都有。如果一篇文章的所有作者都没有名字，Docusaurus 将紧凑地显示他们的头像。查看此测试文章以了解效果。

Feed generation

RSS feeds 需要设置作者的电子邮件，以便作者出现在订阅源中。

作者页面

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

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

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'

博客插件现在将生成：

每个作者的专属页面（示例），列出他们贡献的所有博客文章
一个作者索引页面 (example) 列出所有这些作者，按照他们在 authors.yml 中出现的顺序排列

About inline authors

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

博客文章标签

标签在前言中声明，并引入了另一种分类维度。

可以内联定义标签，或者引用在tags file（可选，通常为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: '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。

tip

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

每篇文章禁用
传递选项
使用自定义算法

在一页上禁用阅读时间：

docusaurus.config.js
export default {
  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
export default {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 100<span class="token punctuation" style="color

Feed

您可以通过传递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; // 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,
              });
            },
          },
        },
      },
    ],
  ],
};

订阅源可以在以下位置找到：

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, // Optional: disable the docs plugin
        blog: {
          routeBasePath: '/', // Serve the blog at the site's root
          /* other blog options */
        },
      },
    ],
  ],
};

warning

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

warning

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

tip

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

多个博客

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

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

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

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

例如，我们在这里托管了第二个博客 here。

初始设置​

添加帖子​

博客列表​

博客侧边栏​

博客发布日期​

博客文章作者​

内联作者​

全局作者​

作者页面​

博客文章标签​

阅读时间​

Feed​

高级主题​

仅博客模式​

多个博客​

初始设置

添加帖子

博客列表

博客侧边栏

博客发布日期

博客文章作者

内联作者

全局作者

作者页面

博客文章标签

阅读时间

Feed

高级主题

仅博客模式

多个博客