Version: 2.0.0-beta.5

📦 plugin-content-blog

Provides the Blog feature and is the default blog plugin for Docusaurus.

Installation#

npm
Yarn

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

yarn add @docusaurus/plugin-content-blog

tip

If you use the preset @docusaurus/preset-classic, you don't need to install this plugin as a dependency.

You can configure this plugin through the preset options.

Configuration#

Accepted fields:

Name	Type	Default	Description
`path`	`string`	`'blog'`	Path to the blog content directory on the filesystem, relative to site dir.
`editUrl`	`string \| EditUrlFunction`	`undefined`	Base URL to edit your site. The final URL is computed by `editUrl + relativeDocPath`. Using a function allows more nuanced control for each file. Omitting this variable entirely will disable edit links.
`editLocalizedFiles`	`boolean`	`false`	The edit URL will target the localized file, instead of the original unlocalized file. Ignored when `editUrl` is a function.
`blogTitle`	`string`	`'Blog'`	Blog page title for better SEO.
`blogDescription`	`string`	`'Blog'`	Blog page meta description for better SEO.
`blogSidebarCount`	`number \| 'ALL'`	`5`	Number of blog post elements to show in the blog sidebar. `'ALL'` to show all blog posts; `0` to disable
`blogSidebarTitle`	`string`	`'Recent posts'`	Title of the blog sidebar.
`routeBasePath`	`string`	`'blog'`	URL route for the blog section of your site. DO NOT include a trailing slash. Use `/` to put the blog at root path.
`include`	`string[]`	`['*/.{md,mdx}']`	Matching files will be included and processed.
`exclude`	`string[]`	See example configuration	No route will be created for matching files.
`postsPerPage`	`number \| 'ALL'`	`10`	Number of posts to show per page in the listing page. Use `'ALL'` to display all posts on one listing page.
`blogListComponent`	`string`	`'@theme/BlogListPage'`	Root component of the blog listing page.
`blogPostComponent`	`string`	`'@theme/BlogPostPage'`	Root component of each blog post page.
`blogTagsListComponent`	`string`	`'@theme/BlogTagsListPage'`	Root component of the tags list page
`blogTagsPostsComponent`	`string`	`'@theme/BlogTagsPostsPage'`	Root component of the "posts containing tag" page.
`remarkPlugins`	`any[]`	`[]`	Remark plugins passed to MDX.
`rehypePlugins`	`any[]`	`[]`	Rehype plugins passed to MDX.
`beforeDefaultRemarkPlugins`	`any[]`	`[]`	Custom Remark plugins passed to MDX before the default Docusaurus Remark plugins.
`beforeDefaultRehypePlugins`	`any[]`	`[]`	Custom Rehype plugins passed to MDX before the default Docusaurus Rehype plugins.
`truncateMarker`	`string`	`/<!--\s(truncate)\s-->/`	Truncate marker, can be a regex or string.
`showReadingTime`	`boolean`	`true`	Show estimated reading time for the blog post.
`authorsMapPath`	`string`	`'authors.yml'`	Path to the authors map file, relative to the blog content directory specified with `path`. Can also be a `json` file.
`feedOptions`	See below	`{type: ['rss', 'atom']}`	Blog feed. If undefined, no rss feed will be generated.
`feedOptions.type`	`'rss' \| 'atom' \| 'all'` (or array of multiple options)	Required	Type of feed to be generated.
`feedOptions.title`	`string`	`siteConfig.title`	Title of the feed.
`feedOptions.description`	`string`	`${siteConfig.title} Blog`	Description of the feed.
`feedOptions.copyright`	`string`	`undefined`	Copyright message.
`feedOptions.language`	`string` (See documentation for possible values)	`undefined`	Language metadata of the feed.

type EditUrlFunction = (params: {  blogDirPath: string;  blogPath: string;  permalink: string;  locale: string;}) => string | undefined;

Example configuration#

Here's an example configuration object.

You can provide it as preset options or plugin options.

tip

Most Docusaurus users configure this plugin through the preset options.

const config = {  path: 'blog',  // Simple use-case: string editUrl  // editUrl: 'https://github.com/facebook/docusaurus/edit/main/website/',  // Advanced use-case: functional editUrl  editUrl: ({locale, blogDirPath, blogPath, permalink}) => {    return `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('remark-math')],  rehypePlugins: [],  beforeDefaultRemarkPlugins: [],  beforeDefaultRehypePlugins: [],  truncateMarker: /<!--\s*(truncate)\s*-->/,  showReadingTime: true,  feedOptions: {    type: '',    title: '',    description: '',    copyright: '',    language: undefined,  },};

Preset 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',          // ... configuration object here        },      },    ],  ],};

Plugin options#

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',        // ... configuration object here      },    ],  ],};

Markdown Frontmatter#

Markdown documents can use the following Markdown FrontMatter metadata fields, enclosed by a line --- on either side.

Accepted fields:

Name	Type	Default	Description
`authors`	`Authors`	`undefined`	List of blog post authors (or unique author). Read the `authors` guide for more explanations. Prefer `authors` over the `author_*` FrontMatter fields, even for single author blog posts.
`author`	`string`	`undefined`	⚠️ Prefer using `authors`. The blog post author's name.
`author_url`	`string`	`undefined`	⚠️ Prefer using `authors`. The URL that the author's name will be linked to. This could be a GitHub, Twitter, Facebook profile URL, etc.
`author_image_url`	`string`	`undefined`	⚠️ Prefer using `authors`. The URL to the author's thumbnail image.
`author_title`	`string`	`undefined`	⚠️ Prefer using `authors`. A description of the author.
`title`	`string`	Markdown title	The blog post title.
`date`	`string`	File name or file creation time	The blog post creation date. If not specified, this can be extracted from the file or folder name, e.g, `2021-04-15-blog-post.mdx`, `2021-04-15-blog-post/index.mdx`, `2021/04/15/blog-post.mdx`. Otherwise, it is the Markdown file creation time.
`tags`	`Tag[]`	`undefined`	A list of strings or objects of two string fields `label` and `permalink` to tag to your post.
`draft`	`boolean`	`false`	A boolean flag to indicate that the blog post is work-in-progress and therefore should not be published yet. However, draft blog posts will be displayed during development.
`hide_table_of_contents`	`boolean`	`false`	Whether to hide the table of contents to the right.
`keywords`	`string[]`	`undefined`	Keywords meta tag, which will become the `<meta name="keywords" content="keyword1,keyword2,..."/>` in `<head>`, used by search engines.
`description`	`string`	The first line of Markdown content	The description of your document, which will become the `<meta name="description" content="..."/>` and `<meta property="og:description" content="..."/>` in `<head>`, used by search engines.
`image`	`string`	`undefined`	Cover or thumbnail image that will be used when displaying the link to your post.
`slug`	`string`	File path	Allows to customize the blog post url (`/<routeBasePath>/<slug>`). Support multiple patterns: `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 filetype AuthorKey = string;
type Author = {  key?: AuthorKey;  name: string;  title?: string;  url?: string;  image_url?: string;};
// The FrontMatter authors field allows various possible shapestype Authors = AuthorKey | Author | (AuthorKey | Author)[];

Example:

---title: Welcome Docusaurus v2authors:  - slorber  - yangshun  - name: Joel Marcey    title: Co-creator of Docusaurus 1    url: https://github.com/JoelMarcey    image_url: https://github.com/JoelMarcey.pngtags: [hello, docusaurus-v2]description: This is my first post on Docusaurus 2.image: https://i.imgur.com/mErPwqL.pnghide_table_of_contents: false---A Markdown blog post

i18n#

Read the i18n introduction first.

Translation files location#

Base path: website/i18n/<locale>/docusaurus-plugin-content-blog
Multi-instance path: website/i18n/<locale>/docusaurus-plugin-content-blog-<pluginId>
JSON files: extracted with docusaurus write-translations
Markdown files: website/i18n/<locale>/docusaurus-plugin-content-blog

Example file-system structure#

website/i18n/<locale>/docusaurus-plugin-content-blog││ # translations for website/blog├── authors.yml├── first-blog-post.md├── second-blog-post.md││ # translations for the plugin options that will be rendered└── options.json