版本：Canary 🚧

博客

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

信息

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

初始设置

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

然后，在 docusaurus.config.js 内创建指向你的博客的链接项。

docusaurus.config.js
module.exports = {
  themeConfig: {
    // ...
    navbar: {
      items: [
        // ...
        {to: 'blog', label: '博客', position: 'left'}, // 或 position: 'right'
      ],
    },
  },
};

新建帖子

要发布博文，只需在 blog 目录中创建一个 Markdown 文件。

比如创建一个 website/blog/2019-09-05-hello-docusaurus-v2.md：

website/blog/2019-09-05-hello-docusaurus-v2.md
---
title: 欢迎来到 Docusaurus v2
description: 这是我关于 Docusaurus 2 的第一篇博文。
slug: welcome-docusaurus-v2
authors:
  - name: Joel Marcey
    title: Docusaurus 1 合作创造者
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
  - name: Sébastien Lorber
    title: Docusaurus 维护者
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
tags: [hello, docusaurus-v2]
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

欢迎来到本博客。 此博客使用 [**Docusaurus 2**](https://docusaurus.io/) 搭建。

<!-- truncate -->

This is my first post on Docusaurus 2.

下方是一系列内容。

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

博文列表

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

在博文中用  来标记文章摘要。摘要部分会在总览所有博文时显示。任何 标记以上的内容都会成为摘要。请注意，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
module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogTitle: 'Docusaurus blog!',
          blogDescription: 'A Docusaurus powered blog!',
          postsPerPage: 'ALL',
        },
      },
    ],
  ],
};

博客侧边栏会展示近期的博客文章。它默认会显示 5 篇，但你可以通过博客插件的 blogSidebarCount 选项来自定义显示的数量。如果你设置 blogSidebarCount: 0，则会直接禁用侧边栏，包括侧边栏的容器。这样就会导致主内容宽度增加。具体表现是：如果设置 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
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          blogSidebarTitle: 'All posts',
          blogSidebarCount: 'ALL',
        },
      },
    ],
  ],
};

博客发布日期

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

提示

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

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

博客文章作者

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.

内联作者

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

Single author
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: [email protected]
---

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

提示

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

信息

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

全局作者

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: [email protected]

slorber:
  name: Sébastien Lorber
  title: Docusaurus maintainer
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png

提示

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

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

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

信息

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

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.

阅读时间

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

docusaurus.config.js
module.exports = {
  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}}),
        },
      },
    ],
  ],
};

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

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
Passing options
Using custom algorithms

Disable reading time on one page:

docusaurus.config.js
module.exports = {
  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!

Pass options to the default reading time function:

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          readingTime: ({content, defaultReadingTime}) =>
            defaultReadingTime({content, options: {wordsPerMinute: 100}}),
        },
      },
    ],
  ],
};

Use a custom implementation of reading time:

docusaurus.config.js
const myReadingTime = require('./myReadingTime');

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

订阅源

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
    /** 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
module.exports = {
  // ...
  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
Atom
JSON

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

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

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

进阶主题

仅博客模式

You can run your Docusaurus 2 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
module.exports = {
  // ...
  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

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!

提示

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
module.exports = {
  // ...
  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.

博客

初始设置​

新建帖子​

博文列表​

博客侧边栏​

博客发布日期​

博客文章作者​

内联作者​

全局作者​

阅读时间​

订阅源​

进阶主题​

仅博客模式​

多个博客​