Blog and Pages

The blog plugin (@docusaurus/plugin-content-blog) reads every Markdown or MDX file in the blog folder, extracts a date, title, authors and tags, and generates the routes shown in the figure: a paginated list, one page per post, tag pages, an archive, optional author pages and, in production builds only, feed files. The pages plugin (@docusaurus/plugin-content-pages) is much simpler: each file under src/pages becomes one route that mirrors its path. Neither plugin needs to be installed when the classic preset is used; both are configured through the preset options blog and pages. The installation page shows where these folders sit in a project, and the configuration page covers the surrounding config file.

The figure shows the inputs of the blog plugin on the left and the routes it generates on the right. The feeds are the only generated files that are missing during docusaurus start.

A site needs a blog folder and, to be reachable from the navbar, a navbar item. The classic template already contains both. The complete configuration below is the one used for the examples on this page; it was built successfully.

Source: Docusaurus docs: Blog

The main blog options, with their defaults from the plugin reference, are these.

Source: Docusaurus docs: plugin-content-blog

The plugin reference also lists replaceable page components (blogListComponent, blogPostComponent, blogTagsListComponent, blogTagsPostsComponent, blogArchiveComponent, blogAuthorsListComponent and blogAuthorsPostsComponent) and the MDX plugin lists remarkPlugins, rehypePlugins, recmaPlugins, beforeDefaultRemarkPlugins and beforeDefaultRehypePlugins.

A post is a Markdown or MDX file in blog. Docusaurus can read the date from the path, so the date does not have to be in the front matter. Supported shapes include 2026-10-15-converting-lengths.mdx, 2026-10-01-pocket-units-1-0/index.md (a folder per post, which is convenient for co-locating images), 2026/10/15/converting-lengths.md and a date folder followed by the file name. The documentation recommends choosing one pattern and applying it everywhere. If the front matter has a date, it can carry a time, which orders several posts of the same day; without any date Docusaurus falls back to the file creation time.

Source: Docusaurus docs: Blog

The front matter fields of a post, from the plugin reference, are summarized below.

Source: Docusaurus docs: plugin-content-blog

In the scratch build the post marked draft: true produced no route, no feed item and no sitemap entry, while the others did.

The blog list page shows each post as a summary: everything above the truncate marker. The part above the marker must be standalone renderable Markdown. Two comment forms are accepted by default, because the default truncateMarker expression matches both <!-- truncate --> and {/* truncate */}. The documentation recommends the HTML comment in .md files and the JSX (MDX) comment in .mdx files.

Source: Docusaurus docs: Blog

The HTML comment is part of the syntax that Docusaurus 3 is phasing out of Markdown files, because MDX itself does not accept HTML comments. The markdown.mdx1Compat.comments option keeps them working and is enabled by default in v3, but it is turned off by the mdx1CompatDisabledByDefault v4 flag. That matters in practice: a site created by create-docusaurus 3.10.2 contains future: { v4: true }, and in that site a post with <!-- truncate --> failed to compile in the scratch build. Switching to the JSX comment, or re-enabling the compatibility option, fixed it. The four outcomes were:

The error printed by the failing build was:

The compatibility option is set as follows. The JSX comment is the successor syntax and works in both modes, so new posts should use it. See the v4 readiness page for the other flags.

Source: Docusaurus docs: Upgrading to Docusaurus 3

This excerpt was not built as a standalone file; the same two options were exercised in the larger site configuration used for the other examples.

A post without a marker is not an error by default. The list shows the whole post and the build prints a warning:

With onUntruncatedBlogPosts: 'throw' the same condition fails the build with that message as the cause.

Authors are declared in the front matter authors field. An author needs at least a name or an image_url. There are three ways to declare one, and they can be mixed in the same list.

The global file is blog/authors.yml (path configurable with authorsMapPath; JSON is also supported, and a localized copy can live under i18n/<locale>/docusaurus-plugin-content-blog/authors.yml).

Source: Docusaurus docs: Blog

The socials map accepts handles for the platforms x, github, twitter, linkedin, stackoverflow, instagram, bluesky, mastodon, threads, twitch, youtube and email; other platforms take a full URL. Setting page: true generates a page per author and an authors index; a page object with a permalink customizes the author’s URL. Only global authors can have a page; inline authors cannot.

In the scratch build the author pages appeared below the blog route, not at the site root:

An override and an inline author look like this.

Source: Docusaurus docs: Blog

Because the inline author is not in authors.yml, the scratch build printed a warning, which becomes an error with onInlineAuthors: 'throw':

Tags are declared in the tags front matter list. A tag is either a key of the optional blog/tags.yml (path set by the tags option; false or null disables the file) or an inline label. Each tag key may define label, permalink and description; any part may be omitted and is inferred from the key. Predefined tags keep tag usage consistent, and onInlineTags: 'throw' rejects every tag that is not in the file.

Source: Docusaurus docs: plugin-content-blog

With the 1.0 post above, which also uses the undeclared tag announcements, the build printed a warning and generated these tag routes:

The tag releases is served at /blog/tags/product-releases because of its permalink; /blog/tags lists all of them. The same tags shape (and the tags file) is used by the docs plugin, described in docs and front matter.

Feeds are generated at build time by feedOptions, so they are only available after docusaurus build, not in development. The default is RSS and Atom. type is 'rss', 'atom', 'json', a list of those, 'all', or null to turn feeds off. The other options are title (default: the site title), description (default: the site title followed by "Blog"), copyright, language, limit (default 20; false or null for all posts), xslt (style the XML feeds so that browsers render them nicely) and createFeedItems (filter or transform items). With the configuration above the build wrote these files, which the blog pages also advertise with alternate link tags in the page head:

Two details matter for authors. The documentation states that RSS feeds only list an author when the author has an email. In the scratch build, the RSS item for the 1.0 post (authors ada and grace) contained the line ada@example.com (Ada Example) and no entry for grace, who has no email, and the JSON feed gave only the first author. Also, the feed description stayed at the default site-title-based value because only title was overridden, so set description when the site title is generic.

Every .js, .jsx, .ts, .tsx, .md and .mdx file under src/pages becomes a route that follows the directory tree: src/pages/index.js is the base URL, src/pages/foo.js is /foo, src/pages/foo/test.js is /foo/test and src/pages/foo/index.js is /foo/. Pages have no sidebar; only documentation does. The /units page of Pocket Units is a React page:

Source: Docusaurus docs: Creating Pages

A React page exports a component. A page does not get the navbar and footer unless its content is wrapped in the Layout component from @theme/Layout; title and description set the head metadata. A directory with an index.tsx is preferred over a single file when the page needs a CSS module next to it, which must be imported explicitly. A Markdown page is simpler but always uses the theme layout:

Source: Docusaurus docs: Creating Pages

Markdown pages are MDX, so they can import and render React components; see MDX and React components and Markdown features for the syntax. The front matter fields documented for Markdown pages are title, description, keywords, image, slug, wrapperClassName, hide_table_of_contents, draft and unlisted. The pages plugin options (set under pages in the preset) are path (src/pages), routeBasePath (/), include (**/*.{js,jsx,ts,tsx,md,mdx}), exclude, mdxPageComponent (@theme/MDXPage), the MDX plugin lists, editUrl, editLocalizedFiles, showLastUpdateAuthor and showLastUpdateTime, the last four applying to Markdown pages only.

By default files and folders whose name starts with _, test files and the __tests__ folder are not turned into pages. The scratch site contained src/pages/_helper.tsx and no /_helper route was created. Keep reusable components in such a place, or outside src/pages, because every other script file in the directory becomes a page.

Two files that map to the same route produce a warning, not a failure. With both about.md and about.tsx the build printed the following and still succeeded; the page served at /about was the Markdown one in this build, although the documentation says only that the last page created wins, so avoid relying on it:

The onDuplicateRoutes site option controls this behavior. A link to a Markdown page may use its file path ([about page](about.md)), which onBrokenLinks validates. For pages that must stay out of the sitemap but reachable, use unlisted: true; for pages under construction, draft: true.

Two documented variations change the shape of the site.