ブログ

ブログ機能を使えば、フル機能のブログをすぐに設置することができます。

情報

ブログプラグインの API リファレンスドキュメントで、オプションの完全な一覧表を確認してください。

初期設定

サイトにブログを設置するには、まずblogというディレクトリを作成してください。

そして、docusaurus.config.jsの中に、あなたのブログへのアイテムリンクを追加します。

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

投稿の追加

ブログで公開するには、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. このブログは[**Docusaurus 2**](https://docusaurus.io/)で作成されています。

<!-- truncate -->

Docusaurus 2に関する最初の記事です。

探究心の塊が続く。

フロントマターは、ブログ記事に著者情報などのメタデータを追加するのに便利ですが、Docusaurusはフロントマターがなくても必要なメタデータをすべて推測することができます。指定可能な全てのフィールドについては、APIドキュメントを参照してください。

ブログリスト

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

ブログ記事内の<!-truncate-->マーカーを使用して、公開されたすべてのブログ記事を表示する際にサマリーとして表示される内容を表します。 より上の部分は、要約の一部となります。トランケートマーカーより上の部分はスタンドアロンでレンダリング可能なMarkdownでなければならないことに注意してください。例：

website/blog/my-post.md
---
title: Markdown blog truncation example
---
これらはすべてブログ投稿のサマリーの一部になります。

<!--truncate-->

ただしここから先は違います。

.mdx 拡張子を使用するファイルには、 MDX コメント {/* truncate */} を代わりに使用します:

website/blog/my-post.mdx
---
title: MDX blog truncation Example
---
これらはすべてブログ投稿のサマリーの一部になります。

{/* truncate */}

しかし、ここから下はそうではありません。

デフォルトでは、各ブログ一覧ページに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 オプションでカスタマイズできます。 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.

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

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

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

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

情報

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

ヒント

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.

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

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

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

フィード

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

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

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

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

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.

初期設定​

投稿の追加​

ブログリスト​

ブログサイドバー​

Blog post date​

Blog post authors​

Inline authors​

Global authors​

Authors pages​

Blog post tags​

Reading time​

フィード​

Advanced topics​

Blog-only mode​

Multiple blogs​