バージョン: 3.5.2

📦 plugin-content-blog

ブログ機能を提供し、Docusaurusのデフォルトのブログプラグインです。

一部の機能は本番環境でのみ利用可能です

フィード機能はビルド出力を抽出することで動作し、本番環境でのみアクティブになります。

インストール

npm
Yarn
pnpm

npm install --save @docusaurus/plugin-content-blog

yarn add @docusaurus/plugin-content-blog

pnpm add @docusaurus/plugin-content-blog

ヒント

プリセット @docusaurus/preset-classic を使用している場合、このプラグインを依存関係としてインストールする必要はありません。

プリセットオプションを使用して、このプラグインを設定できます。

設定

受け入れられるフィールド

名前	タイプ	デフォルト	説明
`path`	`string`	`'blog'`	サイトディレクトリからの相対的な、ファイルシステムのブログコンテンツディレクトリへのパス。
`editUrl`	`string \| EditUrlFn`	`undefined`	サイトを編集するためのベースURL。最終的なURLは、`editUrl + relativePostPath`によって計算されます。関数を使用すると、各ファイルに対してより細かい制御が可能になります。この変数を完全に省略すると、編集リンクが無効になります。
`editLocalizedFiles`	`boolean`	`false`	編集URLは、元の非ローカライズファイルではなく、ローカライズされたファイルを対象とします。 `editUrl`が関数の場合は無視されます。
`blogTitle`	`string`	`'ブログ'`	より良いSEOのためのブログページタイトル。
`blogDescription`	`string`	`'ブログ'`	より良いSEOのためのブログページのメタディスクリプション。
`blogSidebarCount`	`number \| 'ALL'`	`5`	ブログのサイドバーに表示するブログ投稿要素の数。すべてのブログ投稿を表示するには`'ALL'`、無効にするには`0`を指定します。
`blogSidebarTitle`	`string`	`'最近の投稿'`	ブログのサイドバーのタイトル。
`routeBasePath`	`string`	`'blog'`	サイトのブログセクションのURLルート。末尾のスラッシュは含めないでください。ブログをルートパスに配置するには`/`を使用します。
`tagsBasePath`	`string`	`'tags'`	ブログのタグセクションのURLルート。`routeBasePath`に追加されます。
`pageBasePath`	`string`	`'page'`	ブログのページセクションのURLルート。`routeBasePath`に追加されます。
`archiveBasePath`	`string \| null`	`'archive'`	ブログのアーカイブセクションのURLルート。`routeBasePath`に追加されます。末尾のスラッシュは含めないでください。アーカイブの生成を無効にするには`null`を使用します。
`authorsBasePath`	`string`	`'authors'`	ブログの著者ページのURLルート。`path`に追加されます。
`include`	`string[]`	`['*/.{md,mdx}']`	コンテンツパスからの相対的な、ビルドするMarkdownファイルに一致するグロブパターンの配列。
`exclude`	`string[]`	設定例を参照	除外するMarkdownファイルに一致するグロブパターンの配列。`include`オプションに基づいた絞り込みとして機能します。
`postsPerPage`	`number \| 'ALL'`	`10`	リストページに1ページあたりに表示する投稿数。1つのリストページにすべての投稿を表示するには`'ALL'`を使用します。
`blogListComponent`	`string`	`'@theme/BlogListPage'`	ブログリストページのルートコンポーネント。
`blogPostComponent`	`string`	`'@theme/BlogPostPage'`	各ブログ投稿ページのルートコンポーネント。
`blogTagsListComponent`	`string`	`'@theme/BlogTagsListPage'`	タグリストページのルートコンポーネント。
`blogTagsPostsComponent`	`string`	`'@theme/BlogTagsPostsPage'`	「タグを含む投稿」ページのルートコンポーネント。
`blogArchiveComponent`	`string`	`'@theme/BlogArchivePage'`	ブログアーカイブページのルートコンポーネント。
`blogAuthorsPostsComponent`	`string`	`'@theme/Blog/Pages/BlogAuthorsPostsPage'`	ブログ著者ページのルートコンポーネント。
`blogAuthorsListComponent`	`string`	`'@theme/Blog/Pages/BlogAuthorsListPage'`	ブログ著者ページインデックスのルートコンポーネント。
`remarkPlugins`	`any[]`	`[]`	MDXに渡されるRemarkプラグイン。
`rehypePlugins`	`any[]`	`[]`	MDXに渡されるRehypeプラグイン。
`rehypePlugins`	`any[]`	`[]`	RecmaプラグインがMDXに渡されます。
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	デフォルトのDocusaurus Remarkプラグインの前にMDXに渡されるカスタムRemarkプラグイン。
`beforeDefaultRehypePlugins`	`any[]`	`[]`	デフォルトのDocusaurus Rehypeプラグインの前にMDXに渡されるカスタムRehypeプラグイン。
`truncateMarker`	`RegExp`	`/<!--\struncate\s-->/` \| `\{\/\\struncate\s\\/\}/`	概要が終了する場所を示す切り捨てマーカー。
`showReadingTime`	`boolean`	`true`	ブログ投稿の推定読書時間を表示します。
`readingTime`	`ReadingTimeFn`	デフォルトの読書時間	表示される読書時間の数をカスタマイズするためのコールバック。
`authorsMapPath`	`string`	`'authors.yml'`	ブログコンテンツディレクトリからの相対的な、著者マップファイルへのパス。
`feedOptions`	下記参照	`{type: ['rss', 'atom']}`	ブログフィード。
`feedOptions.type`	`FeedType \| FeedType[] \| 'all' \| null`	必須	生成するフィードのタイプ。生成を無効にするには`null`を使用します。
`feedOptions.createFeedItems`	`CreateFeedItemsFn \| undefined`	`undefined`	フィード内のアイテムを変換またはフィルタリングするために使用できるオプションの関数。
`feedOptions.limit`	`number \| null \| false`	`20`	フィードを特定の数の投稿に制限します。すべてのエントリの場合は、`false`または`null`を使用します。デフォルトは`20`です。
`feedOptions.title`	`string`	`siteConfig.title`	フィードのタイトル。
`feedOptions.description`	`string`	`${siteConfig.title} ブログ`	フィードの説明。
`feedOptions.copyright`	`string`	`undefined`	著作権メッセージ。
`feedOptions.xslt`	`boolean \| FeedXSLTOptions`	`undefined`	著作権メッセージ。
`feedOptions.language`	`string` (可能な値については、ドキュメントを参照してください)	`undefined`	フィードの言語メタデータ。
`sortPosts`	`'descending' \| 'ascending'`	`'descending'`	ブログ投稿のソートの方向を制御します。
`processBlogPosts`	`ProcessBlogPostsFn`	`undefined`	ブログ投稿を変換（フィルタリング、変更、削除など）するために使用できるオプションの関数。
`showLastUpdateAuthor`	`boolean`	`false`	ブログ投稿を最後に更新した著者を表示するかどうか。
`showLastUpdateTime`	`boolean`	`false`	ブログ投稿が最後に更新された日付を表示するかどうか。これにはビルド中のGit履歴へのアクセスが必要なため、シャロークローン（CIシステムでは一般的なデフォルト）では正しく機能しません。GitHub `actions/checkout`では、`fetch-depth: 0`を使用してください。
`tags`	`string \| false \| null \| undefined`	`tags.yml`	定義済みのタグをリストしたYAMLタグファイルへのパス。ブログコンテンツディレクトリからの相対パス。
`onInlineTags`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	`warn`	ブログ投稿にインラインタグ（通常は`tags.yml`の定義済みタグのリストに表示されないタグ）が含まれている場合のプラグインの動作。
`onUntruncatedBlogPosts`	`'ignore' \| 'log' \| 'warn' \| 'throw'`	`warn`	ブログ投稿に切り捨てマーカーが含まれていない場合のプラグインの動作。

型

`EditUrlFn`

type EditUrlFunction = (params: {
  blogDirPath: string;
  blogPath: string;
  permalink: string;
  locale: string;
}) => string | undefined;

`ReadingTimeFn`

type ReadingTimeOptions = {
  wordsPerMinute: number;
  wordBound: (char: string) => boolean;
};

type ReadingTimeCalculator = (params: {
  content: string;
  frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
  options?: ReadingTimeOptions;
}) => number;

type ReadingTimeFn = (params: {
  content: string;
  frontMatter: BlogPostFrontMatter & Record<string, unknown>;
  defaultReadingTime: ReadingTimeCalculator;
}) => number | undefined;

`FeedType`

type FeedType = 'rss' | 'atom' | 'json';

`FeedXSLTOptions`

XSLTを使用してブラウザでブログXMLフィードをきれいにレンダリングできるようにスタイル設定を許可します。

ブログに組み込みの.xslファイルと.cssファイルを使用してブログフィードをスタイル設定するにはtrueを使用します
機能を無効にするには、偽の値（undefined | null | false）を使用します。
ブログコンテンツフォルダに対する相対パスとして、カスタムの.xslファイルへのパスをstringで指定します。慣例として、同じ名前の.cssファイルも提供する必要があります。

type FeedXSLTOptions =
  | boolean
  | undefined
  | null
  | {
      rss?: string | boolean | null | undefined;
      atom?: string | boolean | null | undefined;
    };

`CreateFeedItemsFn`

type CreateFeedItemsFn = (params: {
  blogPosts: BlogPost[];
  siteConfig: DocusaurusConfig;
  outDir: string;
  defaultCreateFeedItemsFn: CreateFeedItemsFn;
}) => Promise<BlogFeedItem[]>;

`ProcessBlogPostsFn`

type ProcessBlogPostsFn = (params: {
  blogPosts: BlogPost[];
}) => Promise<void | BlogPost[]>;

設定例

このプラグインは、プリセットオプションまたはプラグインオプションを通じて設定できます。

ヒント

ほとんどのDocusaurusユーザーは、プリセットオプションを通じてこのプラグインを設定します。

プリセットオプション
プラグインオプション

プリセットを使用する場合は、プリセットオプションを通じてこのプラグインを設定してください。

docusaurus.config.js
module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          path: 'blog',
          // Simple use-case: string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // Advanced use-case: functional editUrl
          editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
            `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
          editLocalizedFiles: false,
          blogTitle: 'Blog title',
          blogDescription: 'Blog',
          blogSidebarCount: 5,
          blogSidebarTitle: 'All our posts',
          routeBasePath: 'blog',
          include: ['**/*.{md,mdx}'],
          exclude: [
            '**/_*.{js,jsx,ts,tsx,md,mdx}',
            '**/_*/**',
            '**/*.test.{js,jsx,ts,tsx}',
            '**/__tests__/**',
          ],
          postsPerPage: 10,
          blogListComponent: '@theme/BlogListPage',
          blogPostComponent: '@theme/BlogPostPage',
          blogTagsListComponent: '@theme/BlogTagsListPage',
          blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
          remarkPlugins: [require('./my-remark-plugin')],
          rehypePlugins: [],
          beforeDefaultRemarkPlugins: [],
          beforeDefaultRehypePlugins: [],
          truncateMarker: /<!--\s*(truncate)\s*-->/,
          showReadingTime: true,
          feedOptions: {
            type: '',
            title: '',
            description: '',
            copyright: '',
            language: undefined,
            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,
              });
            },
          },
        },
      },
    ],
  ],
};

スタンドアロンのプラグインを使用している場合は、オプションをプラグインに直接指定してください。

docusaurus.config.js
module.exports = {
  plugins: [
    [
      '@docusaurus/plugin-content-blog',
      {
        path: 'blog',
        // Simple use-case: string editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // Advanced use-case: functional editUrl
        editUrl: ({locale, blogDirPath, blogPath, permalink}) =>
          `https://github.com/facebook/docusaurus/edit/main/website/${blogDirPath}/${blogPath}`,
        editLocalizedFiles: false,
        blogTitle: 'Blog title',
        blogDescription: 'Blog',
        blogSidebarCount: 5,
        blogSidebarTitle: 'All our posts',
        routeBasePath: 'blog',
        include: ['**/*.{md,mdx}'],
        exclude: [
          '**/_*.{js,jsx,ts,tsx,md,mdx}',
          '**/_*/**',
          '**/*.test.{js,jsx,ts,tsx}',
          '**/__tests__/**',
        ],
        postsPerPage: 10,
        blogListComponent: '@theme/BlogListPage',
        blogPostComponent: '@theme/BlogPostPage',
        blogTagsListComponent: '@theme/BlogTagsListPage',
        blogTagsPostsComponent: '@theme/BlogTagsPostsPage',
        remarkPlugins: [require('./my-remark-plugin')],
        rehypePlugins: [],
        beforeDefaultRemarkPlugins: [],
        beforeDefaultRehypePlugins: [],
        truncateMarker: /<!--\s*(truncate)\s*-->/,
        showReadingTime: true,
        feedOptions: {
          type: '',
          title: '',
          description: '',
          copyright: '',
          language: undefined,
          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,
            });
          },
        },
      },
    ],
  ],
};

Markdownフロントマター

Markdownドキュメントでは、両側に---の行で囲まれた以下のMarkdown フロントマターメタデータフィールドを使用できます。

受け入れられるフィールド

名前	タイプ	デフォルト	説明
`authors`	`著者`	`undefined`	ブログ記事の著者（または一意の著者）のリスト。詳細については、`authors`ガイドを参照してください。単一の著者によるブログ記事の場合でも、`author_*`フロントマターフィールドよりも`authors`を優先してください。
`author`	`string`	`undefined`	⚠️ `authors`の使用を推奨します。ブログ記事の著者の名前。
`author_url`	`string`	`undefined`	⚠️ `authors`の使用を推奨します。著者の名前がリンクされるURL。これは、GitHub、Twitter、FacebookのプロフィールURLなどになります。
`author_image_url`	`string`	`undefined`	⚠️ `authors`の使用を推奨します。著者のサムネイル画像へのURL。
`author_title`	`string`	`undefined`	⚠️ `authors`の使用を推奨します。著者の説明。
`title`	`string`	Markdownタイトル	ブログ記事のタイトル。
`date`	`string`	ファイル名またはファイル作成時間	ブログ記事の作成日。指定されていない場合は、ファイル名またはフォルダ名から抽出できます（例：`2021-04-15-blog-post.mdx`、`2021-04-15-blog-post/index.mdx`、`2021/04/15/blog-post.mdx`）。それ以外の場合は、Markdownファイルの作成時間になります。
`tags`	`Tag[]`	`undefined`	投稿にタグ付けするための文字列または2つの文字列フィールド`label`と`permalink`を持つオブジェクトのリスト。文字列は、タグファイル（通常は`tags.yml`）のキーへの参照にできます。
`draft`	`boolean`	`false`	下書きのブログ記事は、開発中にのみ利用できます。
`unlisted`	`boolean`	`false`	非公開のブログ記事は、開発環境と本番環境の両方で利用できます。本番環境では「非表示」になり、インデックス化されず、サイトマップから除外されます。直接リンクを持っているユーザーのみがアクセスできます。
`hide_table_of_contents`	`boolean`	`false`	右側の目次を非表示にするかどうか。
`toc_min_heading_level`	`数値`	`2`	目次に表示される最小見出しレベル。2〜6の間であり、最大値以下である必要があります。
`toc_max_heading_level`	`数値`	`3`	目次に表示される最大見出しレベル。2〜6の間である必要があります。
`keywords`	`string[]`	`undefined`	キーワードのメタタグ。検索エンジンで使用される`<head>`内の`<meta name="keywords" content="keyword1,keyword2,..."/>`になります。
`description`	`string`	Markdownコンテンツの最初の行	ドキュメントの説明。検索エンジンで使用される`<head>`内の`<meta name="description" content="..."/>`と`<meta property="og:description" content="..."/>`になります。
`image`	`string`	`undefined`	ソーシャルメディアやメッセージングプラットフォームでのリンクプレビューを向上させるために、`<head>`内の`<meta property="og:image" content="..."/>`として使用されるカバーまたはサムネイル画像。
`slug`	`string`	ファイルパス	ブログ記事のURL (`/<routeBasePath>/<slug>`) をカスタマイズできます。複数のパターンをサポート: `slug: my-blog-post`、`slug: /my/path/to/blog/post`、slug: `/`。
`last_update`	`FrontMatterLastUpdate`	`undefined`	最終更新の著者/日付を上書きできます。日付は、解析可能な任意の日付文字列にできます。

type FrontMatterLastUpdate = {date?: string; author?: string};

type Tag = string | {label: string; permalink: string};

// An author key references an author from the global plugin authors.yml file
type AuthorKey = string;

// Social platform name -> Social platform link
// Example: {MyPlatform: 'https://myplatform.com/myusername'}
// Pre-defined platforms ("x", "github", "twitter", "linkedin", "stackoverflow") accept handles:
// Example: {github: 'slorber'}
type AuthorSocials = Record<string, string>;

type Author = {
  key?: AuthorKey;
  name: string;
  title?: string;
  url?: string;
  image_url?: string;
  socials?: AuthorSocials;
};

// The front matter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

例

---
title: Welcome Docusaurus
authors:
  - slorber
  - yangshun
  - 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
tags: [docusaurus]
description: This is my first post on Docusaurus.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---

A Markdown blog post

タグファイル

tagsプラグインオプションを使用して、YAMLタグファイルのパスを設定します。

慣例として、プラグインはコンテンツフォルダのルートにあるtags.ymlファイルを検索します。

このファイルには、定義済みのタグのリストを含めることができます。Markdownファイルのtagsフロントマターのおかげで、これらのタグをキーで参照できます。

タグの一貫性を保つ

タグファイルを使用すると、プラグインのコンテンツセット全体でタグの使用が一定であることを保証できます。この一貫性を強制し、その場で宣言されたインラインタグの使用を防ぐには、onInlineTags: 'throw'プラグインオプションを使用してください。

型

提供されたタグファイルのYAMLコンテンツは、以下の構造に従う必要があります

type Tag = {
  label?: string; // Tag display label
  permalink?: string; // Tag URL pathname segment
  description?: string; // Tag description displayed in the tag page
};

type TagsFileInput = Record<string, Partial<Tag> | null>;

例

tags.yml
releases:
  label: 'Product releases'
  permalink: '/product-releases'
  description: 'Content related to product releases.'

# A partial tag definition is also valid
announcements:
  label: 'Announcements'

# An empty tag definition is also valid
# Other attributes will be inferred from the key
emptyTag:

content.md
---
tags: [releases, announcements, emptyTag]
---

# Title

Content

著者ファイル

authorsプラグインオプションを使用して、YAML著者ファイルのパスを設定します。

慣例として、プラグインはブログコンテンツフォルダのルートにあるauthors.ymlファイルを検索します。

このファイルには、定義済みのグローバルブログ著者のリストを含めることができます。Markdownファイルのauthorsフロントマターのおかげで、これらの著者をキーで参照できます。

型

提供された著者ファイルのYAMLコンテンツは、以下の構造に従う必要があります

type AuthorsMapInput = {
  [authorKey: string]: AuthorInput;
};

type AuthorInput = {
  name?: string;
  title?: string;
  description?: string;
  imageURL?: string;
  url?: string;
  email?: string;
  page?: boolean | {permalink: string};
  socials?: Record<string, string>;
  [customAuthorAttribute: string]: unknown;
};

例

tags.yml
slorber:
  name: Sébastien Lorber
  title: Docusaurus maintainer
  url: https://sebastienlorber.com
  image_url: https://github.com/slorber.png
  page: true
  socials:
    x: sebastienlorber
    github: slorber

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]
  page:
    permalink: '/joel-marcey'
  socials:
    x: joelmarcey
    github: JoelMarcey

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

# My Blog Post

Content

i18n

まず、i18nの概要をお読みください。

翻訳ファイルの場所

ベースパス: website/i18n/[locale]/docusaurus-plugin-content-blog
複数インスタンスのパス: website/i18n/[locale]/docusaurus-plugin-content-blog-[pluginId]
JSONファイル: docusaurus write-translationsで抽出
Markdownファイル: website/i18n/[locale]/docusaurus-plugin-content-blog

ファイルシステム構造の例

website/i18n/[locale]/docusaurus-plugin-content-blog
│
│ # translations for website/blog
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # translations for the plugin options that will be rendered
└── options.json

インストール​

設定​

型​

EditUrlFn​

ReadingTimeFn​

FeedType​

FeedXSLTOptions​

CreateFeedItemsFn​

ProcessBlogPostsFn​

設定例​

Markdownフロントマター​

タグファイル​

型​

例​

著者ファイル​

型​

例​

i18n​

翻訳ファイルの場所​

ファイルシステム構造の例​