博客
博客功能可以让你快速部署一个功能齐全的博客。
请查阅博客插件 API 参考文档以获取完整的选项列表。
初始设置
要设置你的网站博客,首先创建一个 blog
目录。
然后,在 docusaurus.config.js
中添加一个指向博客的链接项
export default {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};
添加文章
要在博客中发布,请在博客目录中创建一个 Markdown 文件。
例如,在 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. This blog is created with [**Docusaurus**](https://docusaurus.org.cn/).
<!-- truncate -->
This is my first post on Docusaurus.
A whole bunch of exploration to follow.
前置元数据有助于为你的博文添加更多元数据,例如作者信息,但 Docusaurus 无需前置元数据也能推断出所有必要的元数据。有关所有可能字段,请参阅API 文档。
博客列表
博客的索引页(默认在 /blog
)是博客列表页,所有博文都在此集中显示。
在你的博文中使用 <!--truncate-->
标记来表示查看所有已发布的博文时将显示为摘要的部分。<!--truncate-->
上方的任何内容都将是摘要的一部分。请注意,截断标记上方部分必须是独立可渲染的 Markdown。例如:
---
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.
对于使用 .mdx
扩展名的文件,请改用 MDX 注释 {/* truncate */}
---
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'
,分页将被禁用,所有文章都将显示在第一页。你还可以为博客列表页添加 meta 描述,以获得更好的 SEO 效果。
export default {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 'ALL',
},
},
],
],
};
博客侧边栏
博客侧边栏显示最新的博文。默认显示项目数为 5,但你可以通过插件配置中的 blogSidebarCount
选项进行自定义。通过设置 blogSidebarCount: 0
,侧边栏将完全禁用,其容器也将被移除。这将增加主容器的宽度。特别是,如果设置 blogSidebarCount: 'ALL'
,则会显示所有文章。
你还可以通过 blogSidebarTitle
选项更改侧边栏标题文本。例如,如果你设置了 blogSidebarCount: 'ALL'
,则可以将其从默认的“近期文章”改为“所有文章”。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogSidebarTitle: 'All posts',
blogSidebarCount: 'ALL',
},
},
],
],
};
博文日期
Docusaurus 将从许多模式中提取 YYYY-MM-DD
日期,例如 YYYY-MM-DD-my-blog-post-title.md
或 YYYY/MM/DD/my-blog-post-title.md
。这使你可以轻松地按年、按月对博文进行分组,或使用扁平结构。
支持的日期提取模式
模式 | 示例 |
---|---|
单个文件 | 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 可以使用上述任何命名模式从文章中提取日期。建议选择一种模式并将其应用于所有文章,以避免混淆。
使用文件夹可以方便地将博文图片与 Markdown 文件放在一起。
此命名约定是可选的,你也可以将日期作为前置元数据提供。由于前置元数据遵循支持日期时间表示法的 YAML 语法,如果你需要更精细的发布日期,可以使用前置元数据。例如,如果你在同一天发布了多篇文章,可以根据一天中的时间对它们进行排序:
---
date: 2021-09-13T10:00
---
---
date: 2021-09-13T18:00
---
博文作者
使用 authors
前置元数据字段来声明博文作者。作者至少需要有 name
或 image_url
。Docusaurus 使用 url
、email
和 title
等信息,但也允许其他任何信息。
内联作者
博文作者可以直接在前置元数据中声明
- 单作者
- 多作者
---
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]
socials:
x: joelmarcey
github: JoelMarcey
---
---
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]
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
---
此选项最适合入门,或适用于偶尔、不定期撰稿的作者。
建议使用 authors
前置元数据,但仍支持旧版 author_*
前置元数据。
---
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---
全局作者
对于经常撰写博文的作者,在每篇博文中维护作者信息可能会很繁琐。
可以在配置文件中全局声明这些作者
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]
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
使用 authorsMapPath
插件选项来配置路径。也支持 JSON 格式。
在博文的前置元数据中,你可以引用全局配置文件中声明的作者
- 单作者
- 多作者
---
authors: jmarcey
---
---
authors: [jmarcey, slorber]
---
authors
系统非常灵活,可以适应更高级的用例
混合内联作者和全局作者
你可以大部分时间使用全局作者,同时仍可以使用内联作者
---
authors:
- jmarcey
- slorber
- name: Inline Author name
title: Inline Author Title
url: https://github.com/inlineAuthor
image_url: https://github.com/inlineAuthor
---
本地覆盖全局作者
你可以根据每篇博文的需求自定义全局作者的数据
---
authors:
- key: jmarcey
title: Joel Marcey's new title
- key: slorber
name: Sébastien Lorber's new name
---
作者配置文件的本地化
配置文件可以本地化,只需在以下位置创建其本地化副本:
website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
作者,无论是通过前置元数据还是通过作者映射声明,都需要有姓名或头像,或两者兼备。如果一篇帖子的所有作者都没有姓名,Docusaurus 将紧凑地显示他们的头像。请参阅此测试帖子以查看效果。
RSS 源要求作者的电子邮件已设置,作者才会出现在源中。
作者页面
作者页面功能是可选的,主要适用于多作者博客。
你可以通过在全局作者配置中添加 page: true
属性来为每位作者独立激活此功能
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'
博客插件现在将生成
博文标签
标签在前置元数据中声明,并引入了另一个分类维度。
可以内联定义标签,或引用在标签文件
(可选,通常是 blog/tags.yml
)中声明的预定义标签。
在以下示例中
docusaurus
引用blog/tags.yml
中声明的预定义标签键Releases
是一个内联标签,因为它不存在于blog/tags.yml
中
---
title: 'My blog post'
tags:
- Releases
- docusaurus
---
Content
docusaurus:
label: 'Docusaurus'
permalink: '/docusaurus'
description: 'Blog posts related to the Docusaurus framework'
阅读时间
Docusaurus 根据字数估算每篇博文的阅读时间。我们提供了一个选项来自定义此功能。
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true, // When set to false, the "x min read" won't be shown
readingTime: ({content, locale, frontMatter, defaultReadingTime}) =>
defaultReadingTime({
content,
locale,
options: {wordsPerMinute: 300},
}),
},
},
],
],
};
readingTime
回调函数接收以下参数:
content
:博客内容的文本字符串frontMatter
:前置元数据,键值对形式的记录locale
:当前 Docusaurus 站点的语言环境defaultReadingTime
:默认的内置阅读时间函数。它返回一个数字(阅读时间,单位分钟)或undefined
(禁用此页面的阅读时间)。
默认的阅读时间可以接受附加选项
wordsPerMinute
:每分钟字数,数字类型(默认值:300)
使用回调函数满足你的所有自定义需求
- 按文章禁用
- 传递选项
- 使用自定义算法
禁用某个页面的阅读时间
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true,
readingTime: ({content, locale, frontMatter, defaultReadingTime}) =>
frontMatter.hide_reading_time
? undefined
: defaultReadingTime({content, locale}),
},
},
],
],
};
用法
---
hide_reading_time: true
---
This page will no longer display the reading time stats!
将选项传递给默认阅读时间函数
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content, locale, defaultReadingTime}) =>
defaultReadingTime({
content,
locale,
options: {wordsPerMinute: 100},
}),
},
},
],
],
};
使用自定义阅读时间实现
import myReadingTime from './myReadingTime';
export default {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content, locale}) => myReadingTime(content, locale),
},
},
],
],
};
订阅源
你可以通过传递 feedOptions
来生成 RSS / Atom / JSON 订阅源。默认情况下,生成 RSS 和 Atom 订阅源。要禁用订阅源生成,请将 feedOptions.type
设置为 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[]>;
};
};
使用示例
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,
});
},
},
},
},
],
],
};
订阅源可以在以下地址找到
- RSS
- Atom
- JSON
https://example.com/blog/rss.xml
https://example.com/blog/atom.xml
https://example.com/blog/feed.json
高级主题
仅博客模式
你可以在没有专用着陆页的情况下运行 Docusaurus 站点,而是将博客的文章列表页作为索引页。将 routeBasePath
设置为 '/'
,通过根路径 example.com/
而不是子路径 example.com/blog/
来提供博客服务。
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 */
},
},
],
],
};
别忘了删除 ./src/pages/index.js
中现有的主页,否则会有两个文件映射到相同的路由!
如果禁用文档插件,请不要忘记删除配置文件中其他地方对文档插件的引用。特别是,请务必移除与文档相关的导航栏项目。
还有一个“仅文档模式”,适用于那些只希望使用文档的用户。请阅读仅文档模式以获取详细说明或对 routeBasePath
更详尽的解释。
多个博客
默认情况下,经典主题假定每个网站只有一个博客,因此只包含博客插件的一个实例。如果你想在一个网站上拥有多个博客,那也是可能的!你可以在 docusaurus.config.js
的 plugins
选项中指定另一个博客插件来添加第二个博客。
将 routeBasePath
设置为你希望访问第二个博客的 URL 路由。请注意,这里的 routeBasePath
必须与第一个博客不同,否则可能会出现路径冲突!此外,将 path
设置为包含第二个博客文章的目录的路径。
正如多实例插件文档中所述,你需要为插件分配一个唯一的 ID。
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',
},
],
],
};
例如,我们在此托管了第二个博客。