Version: 2.0.0-beta.9 🚧

📦 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.
`tagsBasePath`	`string`	`'tags'`	URL route for the tags list page of your site. It is prepended to the `routeBasePath`.
`archiveBasePath`	`string`	`'/archive'`	URL route for the archive blog section of your site. It is prepended to the `routeBasePath`. DO NOT include a trailing slash.
`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.
`readingTime`	`ReadingTimeFunctionOption`	The default reading time	A callback to customize the reading time number displayed.
`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;

type ReadingTimeOptions = {
  wordsPerMinute: number;
  wordBound: (char: string) => boolean;
};

type ReadingTimeFunction = (params: {
  content: string;
  frontMatter?: BlogPostFrontMatter & Record<string, unknown>;
  options?: ReadingTimeOptions;
}) => number;

type ReadingTimeFunctionOption = (params: {
  content: string;
  frontMatter: BlogPostFrontMatter & Record<string, unknown>;
  defaultReadingTime: ReadingTimeFunction;
}) => number | 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.
`toc_min_heading_level`	`number`	`2`	The minimum heading level shown in the table of contents. Must be between 2 and 6 and lower or equal to the max value.
`toc_max_heading_level`	`number`	`3`	The max heading level shown in the table of contents. Must be between 2 and 6.
`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 file
type AuthorKey = string;

type Author = {
  key?: AuthorKey;
  name: string;
  title?: string;
  url?: string;
  image_url?: string;
};

// The FrontMatter authors field allows various possible shapes
type Authors = AuthorKey | Author | (AuthorKey | Author)[];

Example:

---
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
---
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

Installation​

tip

Configuration​

Example configuration​

tip

Preset options​

Plugin options​

Markdown Frontmatter​

i18n​

Translation files location​

Example file-system structure​

Installation

Configuration

Example configuration

Preset options

Plugin options

Markdown Frontmatter

i18n

Translation files location

Example file-system structure