Skip to main content

Docusaurus 3.1

· 2 min read
Sébastien Lorber
Sébastien Lorber
Docusaurus maintainer, This Week In React editor

We are happy to announce Docusaurus 3.1.

The upgrade should be easy: as explained in our release process documentation, minor versions respect Semantic Versioning.

Docusaurus blog post social card

Highlights​

Broken anchors checker​

In #9528, we improved the built-in broken links checker to also detect broken anchors.

Docusaurus blog post social card

Make it fail fast

The new onBrokenAnchors option has value warn by default, for retro-compatibility reasons.

We recommend to turn it to throw and fail your CI builds instead of deploying broken anchors to productions.

note

For users and plugin authors implementing custom <Heading> and <Link> components, we provide a new useBrokenLinks React hook API.

Most Docusaurus users don't need to care about it, built-in components (docusaurus/Link and @theme/Heading) already use it internally.

parseFrontMatter hook​

In #9624, we added a new siteConfig.markdown.parseFrontMatter function hook.

This makes it possible to implement convenient front matter transformations, shortcuts, or to integrate with external systems using front matter that Docusaurus plugins do not support.

docusaurus.config.js
export default {
  markdown: {
    parseFrontMatter: async (params) => {
      // Reuse the default parser
      const result = await params.defaultParseFrontMatter(params);

      // Process front matter description placeholders
      result.frontMatter.description =
        result.frontMatter.description?.replaceAll('{{MY_VAR}}', 'MY_VALUE');

      // Create your own front matter shortcut
      if (result.frontMatter.i_do_not_want_docs_pagination) {
        result.frontMatter.pagination_prev = null;
        result.frontMatter.pagination_next = null;
      }

      // Rename an unsupported front matter coming from another system
      if (result.frontMatter.cms_seo_summary) {
        result.frontMatter.description = result.frontMatter.cms_seo_summary;
        delete result.frontMatter.cms_seo_summary;
      }

      return result;
    },
  },
};

Read the front matter guide and the parseFrontMatter API ref for details.

Other changes​

Other notable changes include:

  • #9674: add siteConfig.markdown.remarkRehypeOptions to pass options to remark-rehype, letting you customize things such as MDX footnote label
  • #9671: add code block MagicComments support for (Visual) Basic/Batch/Fortran/COBOL/ML
  • #9610: enable CLI port configuration via PORT environment variable
  • #9477: complete Brazilian Portuguese (pt-BR) translations

Check the 3.1.0 changelog entry for an exhaustive list of changes.