📦 plugin-content-blog

提供 博客 功能，是 Docusaurus 的默认博客插件。

some features production only

Feed 功能 通过提取构建输出工作，并且 仅在生产环境中有效 。

安装

npm

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

Yarn

yarn add @docusaurus/plugin-content-blog

pnpm

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	'Blog'	博客页面标题，用于更好的 SEO。
blogDescription	string	'Blog'	博客页面元描述，用于更好的 SEO。
blogSidebarCount	number | 'ALL'	5	在博客侧边栏中显示的博客文章元素数量。'ALL' 显示所有博客文章；0 禁用。
blogSidebarTitle	string	'Recent posts'	博客侧边栏的标题。
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 文件匹配的 glob 模式数组，相对于内容路径。
exclude	string[]	参见示例配置	与要排除的 Markdown 文件匹配的 glob 模式数组。根据 include 选项进行细化。
postsPerPage	number | 'ALL'	10	列表页面上每页显示的帖子数量。使用 '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[]	[]	传递给 MDX 的 Recma 插件。
beforeDefaultRemarkPlugins	any[]	[]	在默认 Docusaurus Remark 插件之前传递给 MDX 的自定义 Remark 插件。
beforeDefaultRehypePlugins	any[]	[]	在默认 Docusaurus Rehype 插件之前传递给 MDX 的自定义 Rehype 插件。
truncateMarker	RegExp	/<!--\s*truncate\s*-->/ | \{\/\*\s*truncate\s*\*\/\}/	截断标记，标记摘要结束位置。
showReadingTime	boolean	true	显示博客文章的估计阅读时间。
readingTime	ReadingTimeFn	默认阅读时间	用于自定义显示的阅读时间数字的回调函数。
authorsMapPath	string	'authors.yml'	作者映射文件的路径，相对于博客内容目录。
feedOptions	见下文	{type: ['rss', 'atom']}	博客 Feed。
feedOptions.type	FeedType | FeedType[] | 'all' | null	必需	要生成的 Feed 类型。使用 null 禁用生成。
feedOptions.createFeedItems	CreateFeedItemsFn | undefined	undefined	可选函数，用于转换和/或过滤 Feed 中的项目。
feedOptions.limit	number | null | false	20	将 Feed 限制为指定数量的帖子，false 或 null 表示所有条目。默认为 20。
feedOptions.title	string	siteConfig.title	Feed 的标题。
feedOptions.description	string	`${siteConfig.title} Blog`	Feed 的描述。
feedOptions.copyright	string	undefined	版权声明。
feedOptions.xslt	boolean | FeedXSLTOptions	undefined	允许使用 XSLT 样式化博客 XML Feed，以便浏览器能够很好地呈现它们。
feedOptions.language	string (参见 文档 获取可能的取值)	undefined	Feed 的语言元数据。
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

允许样式化博客 XML Feed，以便浏览器使用 XSLT 很好地呈现它们。

• 使用 true 让博客使用其内置的 .xsl 和 .css 文件来样式化博客 Feed
• 使用虚假值（undefined | null | false）禁用此功能
• 使用 string 提供相对于博客内容文件夹的自定义 .xsl 文件的路径。按照约定，您必须提供具有完全相同名称的 .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 用户通过预设选项配置此插件。

Preset options

If you use a preset, configure this plugin through the preset options:

docusaurus.config.js

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        [translation failure]: {
          path: 'blog',
          // 简单用例：string editUrl
          // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
          // 高级用例：函数式 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,
              });
            },
          },
        },
      },
    ],
  ],
};

Plugin options

If you are using a standalone plugin, provide options directly to the plugin:

docusaurus.config.js

module.exports = {
  plugins: [
    [
      '[translation failure]',
      {
        path: 'blog',
        // 简单用例：string editUrl
        // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',
        // 高级用例：函数式 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	Authors	undefined	博客文章作者列表（或唯一作者）。阅读 authors 指南 获取更多解释。即使对于单作者博客文章，也建议使用 authors 而不是 author_* 前端内容字段。
author	string	undefined	⚠️ 建议使用 authors。博客文章作者的姓名。
author_url	string	undefined	⚠️ 建议使用 authors。作者姓名将链接到的 URL。这可以是 GitHub、X、Facebook 个人资料 URL 等。
author_image_url	string	undefined	⚠️ 建议使用 authors。作者缩略图图像的 URL。
author_title	string	undefined	⚠️ 建议使用 authors。作者的描述。
title	string	Markdown 标题	博客文章标题。
sidebar_label	string	title	博客侧边栏的自定义标签，替换默认标签（title）。
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	用于为您的文章添加标签的字符串或包含两个字符串字段 label 和 permalink 的对象的列表。字符串可以是 标签文件 （通常为 tags.yml）的键的引用
draft	boolean	false	草稿博客文章仅在开发期间可用。
unlisted	boolean	false	未列出的博客文章在开发和生产环境中都可用。它们将在生产环境中“隐藏”，不会被索引，从站点地图中排除，并且只能由拥有直接链接的用户访问。
hide_table_of_contents	boolean	false	是否隐藏右侧的目录。
toc_min_heading_level	number	2	目录中显示的最小标题级别。必须介于 2 和 6 之间，并且小于或等于最大值。
toc_max_heading_level	number	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", "instagram", "bluesky", "mastodon", "threads", "twitch", "youtube") 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
---

一篇 Markdown 博客文章

标签文件

使用 tags 插件选项 配置 YAML 标签文件的路径。

按照惯例，插件会在您的内容文件夹的根目录下查找 tags.yml 文件。

此文件可以包含预定义标签的列表。您可以通过 Markdown 文件中的键来引用这些标签，这要感谢 tags 前置 matter 。

保持标签一致

使用标签文件，您可以确保在整个插件内容集中一致地使用标签。使用 onInlineTags: 'throw' 插件选项来强制执行此一致性，并防止使用动态声明的内联标签。

类型

提供的标签文件的 YAML 内容应遵循以下结构：

type Tag = {
  label?: string; // 标签显示标签
  permalink?: string; // 标签 URL 路径段
  description?: string; // 在标签页中显示的标签描述
};

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

示例

tags.yml

releases:
  label: '产品发布'
  permalink: '/product-releases'
  description: '与产品发布相关的內容。'

# 部分标签定义也是有效的
announcements:
  label: '公告'

# 空标签定义也是有效的
# 其他属性将从键中推断
emptyTag:

content.md

---
tags: [releases, announcements, emptyTag]
---

# 标题

内容

作者文件

使用 authors 插件选项 配置 YAML 作者文件的路径。

按照约定，插件将在博客内容文件夹的根目录查找 authors.yml 文件。

此文件可以包含预定义的 全局博客作者 列表。您可以通过 Markdown 文件中的键来引用这些作者，这要感谢 authors 前端内容 。

类型

提供的作者文件应遵循以下结构：

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

# 我的博客文章

内容

国际化

首先阅读 国际化介绍 。

翻译文件位置

• 基本路径 : 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
│
│ # website/blog 的翻译
├── authors.yml
├── first-blog-post.md
├── second-blog-post.md
│
│ # 将要渲染的插件选项的翻译
└── options.json