博客
博客功能允许你可以即时部署一个功能完全的博客。
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. 请注意,Truncate标记以上的部分必须是独立的、可渲染的Markdown。 举个例子:
---
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: 'All posts',
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 路径的开头。
Using a folder can be convenient to co-locate blog post images alongside the Markdown file.
此命名约定是可选的,你也可以提供日期作为前面的内容。 由于 Front Matter 遵循支持日期时间表示法的 YAML 语法,因此如果你需要更细粒度的发布日期,可以使用 Front Matter。 例如,如果你在同一天发布了多个帖子,你可以根据一天中的时间对它们进行排序:
---
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.