博客
博客功能允许你可以即时部署一个功能完全的博客。
Check the Blog Plugin API Reference documentation for an exhaustive list of options.
Initial setup
To set up your site's blog, start by creating a blog
directory.
Then, add an item link to your blog within docusaurus.config.js
:
module.exports = {
themeConfig: {
// ...
navbar: {
items: [
// ...
{to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
],
},
},
};
Adding posts
要发布博文,只需在 blog 目录中创建一个 Markdown 文件。
For example, create a file at website/blog/2019-09-05-hello-docusaurus-v2.md
:
---
title: Welcome Docusaurus v2
description: This is my first post on Docusaurus 2.
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
- name: Sébastien Lorber
title: Docusaurus maintainer
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
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 2**](https://docusaurus.io/).
<!--truncate-->
This is my first post on Docusaurus 2.
A whole bunch of exploration to follow.
The front matter is useful to add more metadata to your blog post, for example, author information, but Docusaurus will be able to infer all necessary metadata without the front matter. For all possible fields, see the API documentation.
Blog list
The blog's index page (by default, it is at /blog
) is the blog list page, where all blog posts are collectively displayed.
Use the <!--truncate-->
marker in your blog post to represent what will be shown as the summary when viewing all published blog posts. Anything above <!--truncate-->
will be part of the summary. 举个例子:
---
title: Truncation Example
---
All these will be part of the blog post summary.
Even this.
<!--truncate-->
But anything from here on down will not be.
Not this.
Or this.
By default, 10 posts are shown on each blog list page, but you can control pagination with the postsPerPage
option in the plugin configuration. If you set postsPerPage: 'ALL'
, pagination will be disabled and all posts will be displayed on the first page. 你也可以在博文列表页添加元描述以进行搜索引擎优化:
module.exports = {
// ...
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogTitle: 'Docusaurus blog!',
blogDescription: 'A Docusaurus powered blog!',
postsPerPage: 'ALL',
},
},
],
],
};
Blog sidebar
博客侧边栏会展示近期的博客文章。 The default number of items shown is 5, but you can customize with the blogSidebarCount
option in the plugin configuration. By setting blogSidebarCount: 0
, the sidebar will be completely disabled, with the container removed as well. 这样就会导致内容宽度增加。 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":
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
blogSidebarTitle: '全部博文',
blogSidebarCount: 'ALL',
},
},
],
],
};
Blog post date
Docusaurus will extract a YYYY-MM-DD
date from a file/folder name such as YYYY-MM-DD-my-blog-post-title.md
.
Example supported patterns
格式 | 示例 |
---|---|
单文件 | 2021-05-28-my-blog-post-title.md |
MDX 文件 | 2021-05-28-my-blog-post-title.mdx |
Single folder + 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 |
Nested folders + index.md | 2021/05/28/my-blog-post-title/index.md |
日期位于路径中间 | category/2021/05-28-my-blog-post-title.md |
日期会从路径中被分离出来,添加到 URL 路径的开头。
使用文件夹的形式,可以方便地把博客所需要的图片等资源和 Markdown 文档放在一起。
这种命名规则不是强制的,你也可以用 Markdown 前言设置发布日期。 由于前言使用的是 YAML 语法,支持日期标记,所以如果你需要更精细的发布日期,可以使用前言。 比如,如果你在同一天发布了多个帖子,你可以根据时间点排列它们:
---
date: 2021-09-13T10:00
---
---
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
博客文章作者可以直接在前言中声明:
- Single author
- Multiple authors
---
authors:
name: Joel Marcey
title: Docusaurus 1 合作创造者
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: [email protected]
---
---
authors:
- name: Joel Marcey
title: Docusaurus 1 合作创造者
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: [email protected]
- name: Sébastien Lorber
title: Docusaurus 维护者
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
---
这个选项最适合上手,或者填写临时,不常规供稿的作者。
Prefer using the authors
front matter, but the legacy author_*
front matter remains supported:
---
author: Joel Marcey
author_title: Docusaurus 1 合作创造者
author_url: https://github.com/JoelMarcey
author_image_url: https://github.com/JoelMarcey.png
---
Global authors
对于规律供稿的博客文章作者来说,在每篇博文中都维护一份作者信息会很麻烦。
可以用一个配置文件,将这些作者全局声明:
jmarcey:
name: Joel Marcey
title: Docusaurus 1 合作创造者
url: https://github.com/JoelMarcey
image_url: https://github.com/JoelMarcey.png
email: [email protected]
slorber:
name: Sébastien Lorber
title: Docusaurus 维护者
url: https://sebastienlorber.com
image_url: https://github.com/slorber.png
Use the authorsMapPath
plugin option to configure the path. JSON 格式也支持。
在博文的前言,你可以引用在全局配置文件中声明的作者:
- Single author
- Multiple authors
---
authors: jmarcey
---
---
authors: [jmarcey, slorber]
---
The authors
system is very flexible and can suit more advanced use-case:
Mix inline authors and global authors
你可以大部分时候使用全局作者,但仍然使用内联作者:
---
authors:
- jmarcey
- slorber
- name: 内联作者名
title: 内联作者头衔
url: https://github.com/inlineAuthor
image_url: https://github.com/inlineAuthor
---
Local override of global authors
你可以在每篇博文中修改一些全局作者数据:
---
authors:
- key: jmarcey
title: Joel Marcey 的新头衔
- key: slorber
name: Sébastien Lorber 的新名字
---
Localize the author's configuration file
配置文件可以被本地化,只需要创建一个本地化的复制版:
website/i18n/[locale]/docusaurus-plugin-content-blog/authors.yml
作者,不论是通过前言声明,还是通过作者映射表声明,都至少需要有姓名或头像中的一个。 如果一篇帖子的所有作者都没有名字,Docusaurus 会紧密地显示他们的头像。 See this test post for the effect.
RSS feeds require the author's email to be set for the author to appear in the feed.
Reading time
Docusaurus 会根据每篇博文的字数生成一个估计阅读时间。 我们提供了一个定制化的选项。
module.exports = {
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
.
用这个回调来满足你的所有自定义需要:
- Per-post disabling
- Passing options
- Using custom algorithms
Disable reading time on one page:
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
showReadingTime: true,
readingTime: ({content, frontMatter, defaultReadingTime}) =>
frontMatter.hide_reading_time
? undefined
: defaultReadingTime({content}),
},
},
],
],
};
用法:
---
hide_reading_time: true
---
这一页不会再显示阅读时间统计了!
Pass options to the default reading time function:
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content, defaultReadingTime}) =>
defaultReadingTime({content, options: {wordsPerMinute: 100}}),
},
},
],
],
};
Use a custom implementation of reading time:
const myReadingTime = require('./myReadingTime');
module.exports = {
presets: [
[
'@docusaurus/preset-classic',
{
blog: {
readingTime: ({content}) => myReadingTime(content),
},
},
],
],
};
Feed
You can generate RSS / Atom / JSON feed by passing feedOptions
. 默认会自动生成 RSS 及 Atom 订阅源。 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
/** 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[]>;
};
};
示例用法:
module.exports = {
// ...
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
Advanced topics
Blog-only mode
你的 Docusaurus 站点可以没有专门编写的首页,而是将博文列表设置为首页。 Set the routeBasePath
to be '/'
to serve the blog through the root route example.com/
instead of the subroute example.com/blog/
.
module.exports = {
// ...
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!
Docusaurus 中还存在「仅文档模式」。 Read Docs-only mode for detailed instructions or a more elaborate explanation of routeBasePath
.
Multiple blogs
默认情况下,经典主题假设一个网站只有一个博客,所以只有一个博客插件实例。 如果你想在同一个站点上部署多个博客,也可以做到! 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.
module.exports = {
// ...
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.