Version: 2.0.0-beta.5

Blog

The blog feature enables you to deploy in no time a full-featured blog.

info

Check the Blog Plugin API Reference documentation for an exhaustive list of options.

Configuração inicial#

Para configurar o blog do seu site, comece criando um diretório blog.

Em seguida, adicione um link do item ao seu blog dentro de docusaurus.config.js:

docusaurus.config.js

module.exports = {  themeConfig: {    // ...    navbar: {      items: [        // ...        {to: 'blog', label: 'Blog', position: 'left'}, // ou position: 'right'      ],    },  },};

Adicionando posts#

To publish in the blog, create a Markdown file within the blog directory.

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

website/blog/2019-09-05-hello-docusaurus-v2.md

---title: Welcome Docusaurus v2description: This is my first post on Docusaurus 2.slug: welcome-docusaurus-v2authors:  - 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.pngtags: [hello, docusaurus-v2]image: https://i.imgur.com/mErPwqL.pnghide_table_of_contents: false---Welcome to this blog. Esse blog foi criado com [**Docusaurus 2**](https://docusaurus.io/).
<!--truncate-->
Esse é o meu primeiro post no Docusaurus 2.
Um monte de exploração para seguir.

note

Docusaurus will extract a YYYY-MM-DD date from a file/folder name such as YYYY-MM-DD-my-blog-post-title.md.

This naming convention is optional, and you can provide the date as FrontMatter.

Example supported patterns

2021-05-28-my-blog-post-title.md
2021-05-28-my-blog-post-title.mdx
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
2021/05/28/my-blog-post-title/index.md
...

tip

Using a folder can be convenient to co-locate blog post images alongside the Markdown file.

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 o marcador  no seu post para demarcar a parte do seu post que será mostrada como resumo ao visualizar todos os posts publicados. Tudo que estiver acima de  será parte do resumo. Por exemplo:

---title: Truncation Example---Tudo isso fará parte do resumo da postagem do blog.
Até isso.
<!--truncate-->
Mas qualquer coisa daqui pra baixo não será.
Isso não.
Nem isso.

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. Você também pode adicionar descrição meta para a página de lista do blog para melhor SEO:

docusaurus.config.js

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

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

docusaurus.config.js

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

Blog post authors#

Use the authors FrontMatter field to declare blog post authors.

Inline authors#

Blog post authors can be declared directly inside the FrontMatter:

Single author
Multiple authors

my-blog-post.md

---authors:  name: Joel Marcey  title: Co-creator of Docusaurus 1  url: https://github.com/JoelMarcey  image_url: https://github.com/JoelMarcey.png---

my-blog-post.md

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

tip

This option works best to get started, or for casual, irregular authors.

info

Prefer usage of the authors FrontMatter, but the legacy author_* FrontMatter remains supported:

my-blog-post.md

---author: Joel Marceyauthor_title: Co-creator of Docusaurus 1author_url: https://github.com/JoelMarceyauthor_image_url: https://github.com/JoelMarcey.png---

Global authors#

For regular blog post authors, it can be tedious to maintain authors information inlined in each blog post.

It is possible declare those authors globally in a configuration file:

website/blog/authors.yml

jmarcey:  name: Joel Marcey  title: Co-creator of Docusaurus 1  url: https://github.com/JoelMarcey  image_url: https://github.com/JoelMarcey.png
slorber:  name: Sébastien Lorber  title: Docusaurus maintainer  url: https://sebastienlorber.com  image_url: https://github.com/slorber.png

tip

Use the authorsMapPath plugin option to configure the path. JSON is also supported.

In blog posts FrontMatter, you can reference the authors declared in the global configuration file:

Single author
Multiple authors

my-blog-post.md

---authors: jmarcey---

my-blog-post.md

---authors: [jmarcey, slorber]---

info

The authors system is very flexible and can suit more advanced use-case:

Mix inline authors and global authors

You can use global authors most of the time, and still use inline authors:

my-blog-post.md

---authors:  - jmarcey  - slorber  - name: Inline Author name    title: Inline Author Title    url: https://github.com/inlineAuthor    image_url: https://github.com/inlineAuthor---

Local override of global authors

You can customize the global author's data on per-blog-post basis

my-blog-post.md

---authors:  - key: jmarcey    title: Joel Marcey's new title  - key: slorber    name: Sébastien Lorber's new name---

Localize the author's configuration file

The configuration file can be localized, just create a localized copy of it at:

website/i18n/<locale>/docusaurus-plugin-content-blog/authors.yml

Feed#

Você pode gerar RSS/Atom feed passando feedOptions. Por padrão, os feeds RSS e Atom são gerados. Para desativar a geração de feed, defina feedOptions.type para 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  };};

Exemplo de Uso:

docusaurus.config.js

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

Acessando o feed:

O feed para RSS pode ser encontrado em:

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

e para o Atom:

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

Tópicos avançados#

Modo somente blog#

Você pode executar o seu site Docusaurus 2 sem uma landing page, em vez disso, ter a página da lista de postagens do seu blog como a página index. Defina o routeBasePath para ser '/' para indicar que é o caminho raiz.

docusaurus.config.js

module.exports = {  // ...  presets: [    [      '@docusaurus/preset-classic',      {        docs: false,        blog: {          path: './blog',          routeBasePath: '/', // Defina este valor como '/'.        },      },    ],  ],};

caution

Não se esqueça de excluir a página inicial existente em ./src/pages/index.js ou então haverá dois arquivos mapeados para a mesma rota!

Vários blogs#

Por padrão, o tema clássico pressupõe apenas um blog por site e, portanto, inclui apenas uma instância do plugin do blog. Se você gostaria de ter vários blogs em um único site, também é possível! Você pode adicionar outro blog, especificando outro plugin no plugin opção para docusaurus.config.js.

Defina o routeBasePath para a rota de URL na qual você deseja que seu segundo blog seja acessado. Observe que o routeBasePath aqui deve ser diferente do primeiro blog ou pode haver uma colisão entre itens! Além disso, defina o caminho para o diretório que contém as entradas do seu segundo blog.

Como documentado para plugins de multi-instância, você precisa atribuir um id exclusivo para os plugins.

docusaurus.config.js

module.exports = {  // ...  plugins: [    [      '@docusaurus/plugin-content-blog',      {        /**         * Obrigatório para qualquer plugin multi-instância         */        id: 'second-blog',        /**         * Rota de URL para a seção do blog do seu site.         * * NÃO * inclua uma barra final.         */        routeBasePath: 'my-second-blog',        /**         * Caminho para os dados no sistema de arquivos relativo ao diretório do site.         */        path: './my-second-blog',      },    ],  ],};

Como exemplo, nós hospedamos um segundo blog aqui.