Docs and Blog
Docusaurus ships two content plugins that behave differently enough to deserve separate mental models. The docs plugin treats the filesystem as an information architecture: a folder becomes a section, a file becomes a page, and a separate file called sidebars.js declares how those pages nest into a navigation tree. The blog plugin treats the filesystem as a feed: every post is a file whose name carries its publication date, and the order, the pagination, the tag pages, and the feed all fall out of that convention. Understanding which of the two models a piece of content belongs to resolves most questions about where a file should live and how it should be configured.
Documentation pages live under docs/ and are addressed by their id. The sidebar is declared in sidebars.js and can mix three entry kinds: a bare document id, a category object with nested items, and an autogenerated entry that reads a directory and builds the tree from frontmatter. Alongside the sidebar, each document carries frontmatter that the page header, the search index, and the previous/next links all read:
| Field | Purpose |
|---|---|
id | The stable identifier other pages link to; defaults to the file name without its extension |
title | The heading shown at the top of the page and in the sidebar |
sidebar_label | A shorter label for the sidebar, useful when title is long |
sidebar_position | Sort order inside an autogenerated section |
tags | Free-form labels that power the tag list at the bottom of a page |
pagination_next / pagination_prev | Override the automatic previous/next document links |
hide_table_of_contents | Suppress the right-hand table of contents for this page |
draft | Exclude the page from a production build |
Categories can carry their own metadata through a _category_.json file placed in the folder, which is how a section gets a label, a description, a position, and a link to an index page without creating a real document for it:
{
"label": "Reference",
"position": 3,
"link": { "type": "generated-index", "description": "Complete API reference." }
}
The feature that distinguishes Docusaurus from most static generators is versioning. When a product ships a release, the documentation for that release must not change afterwards, but the documentation for the next release must be editable. Docusaurus solves this by snapshotting the entire docs folder into a numbered directory and keeping both on the site:
npm run docusaurus docs:version 1.0
npm run docusaurus docs:versions
The first command creates versioned_docs/version-1.0/ and versioned_sidebars/version-1.0-sidebars.json, and records the new version in versions.json. The docs folder remains the unreleased version, usually labeled current in the version dropdown. The configuration file controls how the versions are presented:
// docusaurus.config.js
module.exports = {
// ...
versions: {
current: { label: '2.0.0', path: '2.0.0' },
'1.0': { label: '1.0', path: '1.0' },
},
lastVersion: 'current',
onlyIncludeVersions: ['current', '1.0'],
};
A useful habit is to snapshot the version at the moment you tag a release rather than afterwards, so the published documentation and the released code are guaranteed to describe the same thing. Because a version snapshot is a copy, a bug fix that must go into an old version is made in the versioned folder and committed explicitly, which is noisier in the repository but much safer in practice.
The blog plugin works the other way around. Posts are files named with their date, and the frontmatter carries the metadata the blog list, the tag pages, and the author pages need:
---
title: Shipping faster with the new build pipeline
description: What changed, why it changed, and what you need to do.
authors: [acme-devrel]
tags: [release, performance]
image: /img/blog/build-pipeline.png
---
Builds are now three times faster. Here is what changed.
<!-- truncate -->
The rest of the post continues.
The authors field references a map defined in the configuration, which is where the display name, role, profile URL, and avatar live:
// docusaurus.config.js
module.exports = {
authors: {
'acme-devrel': {
name: 'Acme DevRel',
title: 'Developer Relations',
url: 'https://acme.dev/team',
imageURL: 'https://acme.dev/avatars/devrel.png',
},
},
blog: {
blogTitle: 'Acme Blog',
blogDescription: 'Release notes and engineering write-ups.',
blogSidebarCount: 10,
postsPerPage: 8,
showLastUpdateTime: true,
feedOptions: {
type: 'all',
title: 'Acme Blog',
description: 'Release notes and engineering write-ups.',
copyright: `Acme, ${new Date().getFullYear()}`,
},
},
};
The <!-- truncate --> marker cuts the post at that point to produce the excerpt used on the list page and in the feed. Setting feedOptions.type to rss or atom publishes a corresponding feed file, and type: 'all' emits both.
Comparing the two models directly makes the difference concrete:
| Aspect | Docs plugin | Blog plugin |
|---|---|---|
| Organization | Folders form sections, sidebars.js forms the tree | One flat folder, date in the filename |
| Ordering | sidebar_position and explicit sidebar entries | Publication date, newest first |
| Navigation | Sidebar shown on every page | List page, plus tag and author pages |
| Versioning | Built-in snapshots per release | Not versioned |
| Authorship | Usually implicit | First-class, with optional author pages |
| Feeds | None | RSS or Atom via feedOptions |
One last detail ties the two together and matters more than it looks: the editUrl option in the docs plugin options adds an “Edit this page” link that points at the source file on your repository, and showLastUpdateTime displays the last commit date for each page. On an internal documentation set maintained by many people, that pair converts readers into contributors and is often worth more than any layout change.
