📦 plugin-content-blog
Docusaurus 的默认博客插件,提供了博客功能。
some features production only
订阅源功能通过提取构建输出实现,仅在生产环境中可用。
安装流程
- 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 | '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 后面。 不要包含末尾斜杠。 |
archiveBasePath | string | null | 'archive' | 博客归档部分的 URL 前缀。 会被添加到 routeBasePath 后面。 不要包含末尾斜杠。 null 会禁止生成博客归档。 |
include | string[] | ['**/*.{md,mdx}'] | 相对于内容路径的 glob 模式列表,匹配到的 Markdown 文件会被构建。 |
exclude | string[] | 见示例配置 | Glob 模式列表,匹配到的 Markdown 文件会被排除。 在 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' | 博客归档页的根组件。 |
remarkPlugins | any[] | [] | 传递给 MDX 的 Remark 插件。 |
rehypePlugins | any[] | [] | 传递给 MDX 的 Rehype 插件。 |
beforeDefaultRemarkPlugins | any[] | [] | 在 Docusaurus 默认 Remark 插件之前传递给 MDX 的自定义 Remark 插件。 |
beforeDefaultRehypePlugins | any[] | [] | 在 Docusaurus 默认 Rehype 插件之前传递给 MDX 的自定义 Rehype 插件。 |
truncateMarker | RegExp | /<!--\s*(truncate)\s*-->/ | 标明摘要结束处的标记。 |
showReadingTime | boolean | true | 在博文上显示估计阅读时间。 |
readingTime | ReadingTimeFn | 默认阅读时间 | 用于自定义显示的阅读时间数字的回调。 |
authorsMapPath | string | 'authors.yml' | 作者记录表的文件路径,相对于博客内容目录。 |
feedOptions | 见下文 | {type: ['rss', 'atom']} | 博客订阅源。 |
feedOptions.type | FeedType | FeedType[] | 'all' | null | 必填 | 要生成的订阅源类型。 null 会禁用订阅源生成。 |
feedOptions.title | string | siteConfig.title | 订阅源的标题。 |
feedOptions.description | string | `${siteConfig.title} Blog` | 订阅源的描述。 |
feedOptions.copyright | string | undefined | 版权信息。 |
feedOptions.language | string (所有可选值请见文档) | undefined | 订阅源的语言元数据。 |
sortPosts | 'descending' | 'ascending' | 'descending' | 决定博文排序的方向。 |
类型
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';
示例配置
你可以通过预设选项或插件选项来配置这个插件。
提示
大多数 Docusaurus 用户通过预设选项配置此插件。
- Preset options
- Plugin options
If you use a preset, configure this plugin through the preset options:
docusaurus.config.js
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
path: 'blog',
// 一般使用场景:字符串 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: '博客标题',
blogDescription: '博客',
blogSidebarCount: 5,
blogSidebarTitle: '我们的所有博文',
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('remark-math')],
rehypePlugins: [],
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
truncateMarker: /<!--\s*(truncate)\s*-->/,
showReadingTime: true,
feedOptions: {
type: '',
title: '',
description: '',
copyright: '',
language: undefined,
},
},
},
],
],
};
If you are using a standalone plugin, provide options directly to the plugin:
docusaurus.config.js
module.exports = {
plugins: [
[
'@docusaurus/plugin-content-blog',
{
path: 'blog',
// 一般使用场景:字符串 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: '博客标题',
blogDescription: '博客',
blogSidebarCount: 5,
blogSidebarTitle: '我们的所有博文',
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('remark-math')],
rehypePlugins: [],
beforeDefaultRemarkPlugins: [],
beforeDefaultRehypePlugins: [],
truncateMarker: /<!--\s*(truncate)\s*-->/,
showReadingTime: true,
feedOptions: {
type: '',
title: '',
description: '',
copyright: '',
language: undefined,
},
},
],
],
};
Markdown 前言
Markdown 文档可以使用以下前言元数据字段。前言的两端应用 ---
包裹。
接受的字段:
参数 | 类型 | 默认值 | 描述 |
---|---|---|---|
authors | Authors | undefined | 博文作者列表(或者唯一作者)。 更多阐释可以参见 authors 指南。 即使文章只有一个作者,也推荐用 authors 而不是 author_* 字段。 |
author | string | undefined | ⚠️ 推荐使用 authors 。 博文作者的名字。 |
author_url | string | undefined | ⚠️ 推荐使用 authors 。 作者名字链接指向的 URL。 可以是 GitHub、Twitter、Facebook 个人主页,等等。 |
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 | 一个列表,由字符串或者包含 label 和 permalink 字符串字段的对象构成,用于提供博文标签。 |
draft | 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 | 显示文档链接时所用的缩略图或封面。 |
slug | string | 文件路径 | 自定义博文的 URL (/<routeBasePath>/<slug> )。 支持多种形式: slug: my-blog-post 、slug: /my/path/to/blog/post 、slug: / 。 |
type Tag = string | {label: string; permalink: string};
// An author key references an author from the global plugin authors.yml file
type AuthorKey = string;
type Author = {
key?: AuthorKey;
name: string;
title?: string;
url?: string;
image_url?: string;
};
// The front matter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];
示例:
---
title: Welcome Docusaurus v2
authors:
- slorber
- yangshun
- name: Joel Marcey
title: Co-creator of Docusaurus 1
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
tags: [hello, docusaurus-v2]
description: This is my first post on Docusaurus 2.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
一篇 Markdown 博文
i18n
Read the i18n introduction first.
翻译文件位置
- 基础路径:
website/i18n/[语言]/docusaurus-plugin-content-blog
- 多实例路径:
website/i18n/[语言]/docusaurus-plugin-content-blog-[插件 ID]
- JSON files: extracted with
docusaurus write-translations
- Markdown 文件:
website/i18n/[语言]/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