跳到主要内容

博客

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

信息

查看博客插件 API 参考文档获取详尽的选项列表。

初始设置​

要设置您站点的博客，首先创建一个 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**](https://docusaurus.io/).

<!-- truncate -->

This is my first post on Docusaurus.

A whole bunch of exploration to follow.

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

博客列表​

博客的索引页面（默认情况下，它位于 /blog）是_博客列表页面_，其中集中显示所有博客文章。

在您的博客文章中使用 <!--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.

对于使用 .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'，您可能希望将默认的"Recent posts"改为"All posts"：

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。这使您能够轻松地按年、按月对博客文章进行分组，或使用扁平结构。

支持的日期提取模式
模式示例
单个文件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

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

提示

使用文件夹可以方便地将博客文章图像与 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 等信息，但也允许任何其他信息。

内联作者​

博客文章作者可以直接在前置元数据中声明：

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

这个选项最适合入门，或者用于偶尔、不定期的作者。

信息

建议使用 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: 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 格式。

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

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

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.

Feed generation

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.

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'

Reading time​

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

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, locale, frontMatter, defaultReadingTime}) =>
            frontMatter.hide_reading_time
              ? undefined
              : defaultReadingTime({content, locale}),
        },
      },
    ],
  ],
};

Usage:

---
hide_reading_time: true
---

This page will no longer display the reading time stats!

Feed​

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

Advanced topics​

Blog-only mode​

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.

Multiple blogs​

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.