docusaurus/website/docs/blog.md

id	title
blog	Blog

Initial setup

To setup 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: [
        // ...
        // highlight-next-line
        {to: 'blog', label: 'Blog', position: 'left'}, // or position: 'right'
      ],
    },
  },
};

Adding posts

To publish in the blog, create a file within the blog directory with a formatted name of YYYY-MM-DD-my-blog-post-title.md. The post date is extracted from the file name.

For example, at my-website/blog/2019-09-05-hello-docusaurus-v2.md:

---
title: Welcome Docusaurus v2
author: Joel Marcey
author_title: Co-creator of Docusaurus 1
author_url: https://github.com/JoelMarcey
author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200
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
---
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 only required field in the front matter is title; however, we provide options to add more metadata to your blog post, for example, author information. 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. For example:

---
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. You can also add meta description to the blog list page for better SEO:

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          // highlight-start
          blogTitle: 'Docusaurus blog!',
          blogDescription: 'A Docusaurus powered blog!',
          postsPerPage: 20,
          // highlight-end
        },
      },
    ],
  ],
};

Blog sidebar

The blog sidebar displays recent blog posts. 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. This will increase the width of the main container. 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 would rather make it say "All posts":

module.exports = {
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          // highlight-start
          blogSidebarTitle: 'All posts',
          blogSidebarCount: 'ALL',
          // highlight-end
        },
      },
    ],
  ],
};

:::note

Because the sidebar title is hard-coded in the configuration file, it is currently untranslatable.

:::

Feed

You can generate RSS/Atom feed by passing feedOptions. By default, RSS and Atom feeds are generated. To disable feed generation, set feedOptions.type to null.

type BlogOptions = {
  feedOptions?: {
    type?: 'rss' | 'atom' | 'all' | null;
    title?: string;
    description?: string;
    copyright: string;
    language?: string; // possible values: http://www.w3.org/TR/REC-html40/struct/dirlang.html#langcodes
  };
};

Example usage:

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        blog: {
          feedOptions: {
            type: 'all',
            copyright: `Copyright © ${new Date().getFullYear()} Facebook, Inc.`,
          },
        },
      },
    ],
  ],
};

Accessing the feed:

The feed for RSS can be found at:

https://{your-domain}/blog/rss.xml

and for Atom:

https://{your-domain}/blog/atom.xml

Advanced topics

Blog-only mode

You can run your Docusaurus 2 site without a landing page and instead have your blog's post list page as the index page. Set the routeBasePath to be '/' to indicate it's the root path.

module.exports = {
  // ...
  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: false,
        blog: {
          path: './blog',
          routeBasePath: '/', // Set this value to '/'.
        },
      },
    ],
  ],
};

:::caution

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!

:::

Multiple blogs

By default, the classic theme assumes only one blog per website and hence includes only one instance of the blog plugin. If you would like to have multiple blogs on a single website, it's possible too! 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.