Skip to main content

Documentation Notes

Staying current​

Support and Discussion​

Reference​

  • Showcase: Showcase of different sites built using Docusaurus. It can be helpful to draw inspiration from what others have done in terms of styling, components, etc.
  • Infima: Styling framework used by Docusaurus under the hood.
  • Awesome Docusaurus: Community curated list of Docusaurus resources.

GitHub​

API​

CLI​

Docusaurus CLI provides a set of scripts to help you generate, serve, and deploy your website. Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager. This link covers the different Docusaurus CLI commands.

Includes details on scripts of the following form: 

docusaurus start|build|swizzle|deploy|serve|clear|write-translations|write-heading-ids [options]

Client API​

The Docusaurus client API provides some APIs on the clients that can be helpful to you when building your site. Includes contents on a variety of useful things.

Components:

  • <ErrorBoundary />
  • <Head/>
  • <Link/>
  • <Redirect/>
  • <BrowserOnly/>
  • <Interpolate/>
  • <Translate/>

Hooks:

  • useDocusaurusContext
  • useIsBrowser
  • useBaseUrl
  • useBaseUrlUtils
  • useGlobalData
  • usePluginData
  • useAllPluginInstancesData

Functions:

  • interpolate
  • translate

Modules:

  • ExecutionEnvironment
  • constants

Site configuration file​

docusaurus.config.js contains configurations for your site and is placed in the root directory of your site. It usually exports a site configuration object.

Required fields:

  • title
  • url
  • baseUrl

Optional fields:

  • favicon
  • trailingSlash
  • i18n
  • noIndex
  • onBrokenLinks
  • onBrokenMarkdownLinks
  • onDuplicateRoutes
  • tagline
  • organizationName
  • projectName
  • deploymentBranch
  • githubHost
  • githubPort
  • themeConfig
  • plugins
  • themes
  • presets
  • customFields
  • staticDirectories
  • scripts
  • stylesheets
  • clientModules
  • ssrTemplate
  • titleDelimiter
  • baseUrlIssueBanner

Plugins​

A variety of plugins are available.

Content Plugins

These plugins are responsible for loading your site's content, and creating pages for your theme to render.

PluginDescription
@docusaurus/plugin-content-docsProvides the Docs functionality and is the default docs plugin for Docusaurus.
@docusaurus/plugin-content-blogProvides the Blog feature and is the default blog plugin for Docusaurus.
@docusaurus/plugin-content-pagesThe default pages plugin for Docusaurus. The classic template ships with this plugin with default configurations. This plugin provides creating pages functionality.

Behavior Plugins

These plugins will add a useful behavior to your Docusaurus site.

PluginDescription
@docusaurus/plugin-client-redirectsDocusaurus Plugin to generate client-side redirects. This plugin will write additional HTML pages to your static site that redirect the user to your existing Docusaurus pages with JavaScript.
@docusaurus/plugin-debugThe debug plugin will display useful debug information at http://localhost:3000/__docusaurus/debug. Mostly useful for plugin authors.
@docusaurus/plugin-google-analyticsThe default Google Analytics plugin. It is a JavaScript library for measuring how users interact with your website in the production build. If you are using Google Analytics 4 you might need to consider using plugin-google-gtag instead.
@docusaurus/plugin-google-gtagThe default Global Site Tag (gtag.js) plugin. It is a JavaScript tagging framework and API that allows you to send event data to Google Analytics, Google Ads, and Google Marketing Platform. This section describes how to configure a Docusaurus site to enable global site tag for Google Analytics.
@docusaurus/plugin-ideal-imageDocusaurus Plugin to generate an almost ideal image (responsive, lazy-loading, and low quality placeholder). By default, the plugin is inactive in development so you could always view full-scale images. If you want to debug the ideal image behavior, you could set the disableInDev option to false.
@docusaurus/plugin-pwaDocusaurus Plugin to add PWA support using Workbox. This plugin generates a Service Worker in production build only, and allows you to create fully PWA-compliant documentation site with offline and installation support.
@docusaurus/plugin-sitemapThis plugin creates sitemaps for your site so that search engine crawlers can crawl your site more accurately.

Themes​

Official Docusaurus themes are provided (more are planned).

ThemeDescription
ConfigurationThis configuration applies to all main themes.
@docusaurus/theme-classicYou can refer to the theme configuration page for more details on the configuration.
@docusaurus/theme-live-codeblockThis theme provides a @theme/CodeBlock component that is powered by react-live. You can read more on interactive code editor documentation.
@docusaurus/theme-search-algoliaThis theme provides a @theme/SearchBar component that integrates with Algolia DocSearch easily. Combined with @docusaurus/theme-classic, it provides a very easy search integration. You can read more on search documentation.

See the configuration page for more on all the possibilities for what can be customized. A small outline (from July 13, 2022):

  • Common
    • Color mode
    • Meta image
    • Metadata
    • Announcement bar
  • Navbar
    • Navbar logo
    • Navbar items
      • Navbar link
      • Navbar dropdown
      • Navbar doc link
      • Navbar linked to a sidebar
      • Navbar docs version dropdown
      • Navbar docs version
      • Navbar locale dropdown
      • Navbar search
      • Navbar with custom HTML
    • Auto-hide sticky navbar
    • Navbar style
  • CodeBlock
    • Theme
    • Default language
  • Footer
    • Footer Links
  • Table of Contents
  • Hooks
    • useColorMode
  • i18n
    • Translation files location
    • Example file-system structure

Client exports​

What are client exports? When you see something like import BrowserOnly from '@docusaurus/BrowserOnly';, know that the BrowserOnly.tsx file is located in the directory referenced in the link above. Here are some of the other files:

  • BrowserOnly.tsx
  • ComponentCreator.tsx
  • ErrorBoundary.tsx
  • ExecutionEnvironment.ts
  • Head.tsx
  • Interpolate.tsx
  • Link.tsx
  • Noop.ts
  • Translate.tsx
  • constants.ts
  • isInternalUrl.ts
  • renderRoutes.ts
  • router.ts
  • useBaseUrl.ts
  • useDocusaurusContext.ts
  • useGlobalData.ts
  • uselsBrowser.ts
  • useRouteContext.tsx

Theme components and customization​

The docusaurus-theme-classic components are useful for swizzling and customization (the link above links to the source code for these components). See the advanced routing docs guide for more helpful details.

Below is a list of some of the components and files related to docusaurus-theme-classic.

  • Admonition
  • AnnouncementBar
  • BackToTopButton
  • BlogArchivePage
  • BlogLayout
  • BlogListPage
  • BlogListPaginator
  • BlogPostitem
  • BlogPostitems
  • BlogPostPage
  • BlogPostPaginator
  • BlogSidebar
  • BlogTagsListPage
  • BlogTagsPostsPage
  • CodeBlock
  • ColorModeToggle
  • Details
  • DocBreadcrumbs
  • DocCard
  • DocCardList
  • DocCategoryGeneratedIndexPage
  • Docitem
  • DocPage
  • DocPaginator
  • DocSidebar
  • DocSidebarltem
  • DocSidebarltems
  • DocTagDocListPage
  • DocTagsListPage
  • DocVersionBadge
  • DocVersionBanner
  • EditThisPage
  • Footer
  • Heading
  • Icon
  • LastUpdated
  • Layout
  • Logo
  • MDXComponents
  • MDXContent
  • MDXPage
  • Navbar
  • Navbarltem
  • PaginatorNavLink
  • SearchMetadata
  • SiteMetadata
  • SkipToContent
  • TOC
  • TOCCollapsible
  • TOCInline
  • TOCitems
  • Tabitem
  • Tabs
  • Tag
  • TagsListByLetter
  • TagsListinline
  • Themedimage
  • ErrorPageContent.tsx
  • NotFound.tsx
  • SearchBar.tsx
  • prism-include-languages.ts

Visit the link to see the source code and/or execute

npm run swizzle -- --list

to see a summary of what kind of swizzling is allowed and/or recommended. Sample output (from Jul 13, 2022 using 2.0.0-beta.22) is included below.

Sample output from npm run swizzle -- --list

Components available for swizzle in @docusaurus/theme-classic:

Component nameWrapEject Description
CodeBlockSafeSafeThe component used to render multi-line code blocks, generally used in Markdown files.
ColorModeToggleSafeSafeThe color mode toggle to switch between light and dark mode.
FooterSafeSafeThe footer component of you site's layout
Footer/CopyrightSafeSafeThe footer copyright
Footer/LayoutSafeSafeThe footer main layout component
Footer/LinkItemSafeSafeThe footer link item component
Footer/LinksSafeSafeThe footer component rendering the footer links
Footer/Links/MultiColumnSafeSafeThe footer component rendering the footer links with a multi-column layout
Footer/Links/SimpleSafeSafeThe footer component rendering the footer links with a simple layout (single row)
Footer/LogoSafeSafeThe footer logo
Icon/ArrowSafeSafeThe arrow icon component
Icon/DarkModeSafeSafeThe dark mode icon component.
Icon/EditSafeSafeThe edit icon component
Icon/LightModeSafeSafeThe light mode icon component.
Icon/MenuSafeSafeThe menu icon component
MDXComponents/ASafeSafeThe component used to render <a> tags and Markdown links in MDX
MDXComponents/CodeSafeSafeThe component used to render <code> tags and Markdown code blocks in MDX
MDXComponents/DetailsSafeSafeThe component used to render <details> tags in MDX
MDXComponents/HeadingSafeSafeThe component used to render heading tags (<h1>, <h2>...) and Markdown headings in MDX
MDXComponents/ImgSafeSafeThe component used to render <img> tags and Markdown images in MDX
MDXComponents/PreSafeSafeThe component used to render <pre> tags in MDX
MDXComponents/UlSafeSafeThe component used to render <ul> tags and Markdown unordered lists in MDX
MDXContentSafeSafeA component wrapping all MDX content and providing the MDXComponents to the MDX context
NotFoundSafeSafeThe global 404 page of your site, meant to be ejected and customized
SearchBarSafeSafeThe search bar component of your site, appearing in the navbar.
DocSidebarSafeUnsafeThe sidebar component on docs pages
MDXComponentsForbiddenSafeThe MDX components to use for rendering MDX files. Meant to be ejected.
NavbarItem/ComponentTypesForbiddenSafeThe Navbar item components mapping. Can be ejected to add custom navbar item types. See https://github.com/facebook/docusaurus/issues/7227.
prism-include-languagesForbiddenSafeThe Prism languages to include for code block syntax highlighting. Meant to be ejected.
AdmonitionUnsafeUnsafeN/A
AnnouncementBarUnsafeUnsafeN/A
BackToTopButtonUnsafeUnsafeN/A
BlogArchivePageUnsafeUnsafeN/A
BlogLayoutUnsafeUnsafeN/A
BlogListPageUnsafeUnsafeN/A
BlogListPaginatorUnsafeUnsafeN/A
BlogPostItemUnsafeUnsafeN/A
BlogPostItem/ContainerUnsafeUnsafeN/A
BlogPostItem/ContentUnsafeUnsafeN/A
BlogPostItem/FooterUnsafeUnsafeN/A
BlogPostItem/Footer/ReadMoreLinkUnsafeUnsafeN/A
BlogPostItem/HeaderUnsafeUnsafeN/A
BlogPostItem/Header/AuthorUnsafeUnsafeN/A
BlogPostItem/Header/AuthorsUnsafeUnsafeN/A
BlogPostItem/Header/InfoUnsafeUnsafeN/A
BlogPostItem/Header/TitleUnsafeUnsafeN/A
BlogPostItemsUnsafeUnsafeN/A
BlogPostPageUnsafeUnsafeN/A
BlogPostPage/MetadataUnsafeUnsafeN/A
BlogPostPaginatorUnsafeUnsafeN/A
BlogSidebarUnsafeUnsafeN/A
BlogSidebar/DesktopUnsafeUnsafeN/A
BlogSidebar/MobileUnsafeUnsafeN/A
BlogTagsListPageUnsafeUnsafeN/A
BlogTagsPostsPageUnsafeUnsafeN/A
CodeBlock/ContainerUnsafeUnsafeN/A
CodeBlock/ContentForbiddenUnsafeN/A
CodeBlock/Content/ElementUnsafeUnsafeN/A
CodeBlock/Content/StringUnsafeUnsafeN/A
CodeBlock/CopyButtonUnsafeUnsafeN/A
CodeBlock/LineUnsafeUnsafeN/A
CodeBlock/WordWrapButtonUnsafeUnsafeN/A
DetailsUnsafeUnsafeN/A
DocBreadcrumbsUnsafeUnsafeN/A
DocCardUnsafeUnsafeN/A
DocCardListUnsafeUnsafeN/A
DocCategoryGeneratedIndexPageUnsafeUnsafeN/A
DocItemUnsafeUnsafeN/A
DocItem/ContentUnsafeUnsafeN/A
DocItem/FooterUnsafeUnsafeN/A
DocItem/LayoutUnsafeUnsafeN/A
DocItem/MetadataUnsafeUnsafeN/A
DocItem/PaginatorUnsafeUnsafeN/A
DocItem/TOCForbiddenUnsafeN/A
DocItem/TOC/DesktopUnsafeUnsafeN/A
DocItem/TOC/MobileUnsafeUnsafeN/A
DocPageUnsafeUnsafeN/A
DocPage/LayoutUnsafeUnsafeN/A
DocPage/Layout/MainUnsafeUnsafeN/A
DocPage/Layout/SidebarUnsafeUnsafeN/A
DocPage/Layout/Sidebar/ExpandButtonUnsafeUnsafeN/A
DocPaginatorUnsafeUnsafeN/A
DocSidebar/DesktopUnsafeUnsafeN/A
DocSidebar/Desktop/CollapseButtonUnsafeUnsafeN/A
DocSidebar/Desktop/ContentUnsafeUnsafeN/A
DocSidebar/MobileUnsafeUnsafeN/A
DocSidebarItemUnsafeUnsafeN/A
DocSidebarItem/CategoryUnsafeUnsafeN/A
DocSidebarItem/HtmlUnsafeUnsafeN/A
DocSidebarItem/LinkUnsafeUnsafeN/A
DocSidebarItemsUnsafeUnsafeN/A
DocTagDocListPageUnsafeUnsafeN/A
DocTagsListPageUnsafeUnsafeN/A
DocVersionBadgeUnsafeUnsafeN/A
DocVersionBannerUnsafeUnsafeN/A
EditThisPageUnsafeUnsafeN/A
ErrorPageContentUnsafeUnsafeN/A
HeadingUnsafeUnsafeN/A
IconForbiddenUnsafeN/A
Icon/CloseUnsafeUnsafeN/A
Icon/ExternalLinkUnsafeUnsafeN/A
Icon/HomeUnsafeUnsafeN/A
Icon/LanguageUnsafeUnsafeN/A
LastUpdatedUnsafeUnsafeN/A
LayoutUnsafeUnsafeN/A
Layout/ProviderUnsafeUnsafeN/A
LogoUnsafeUnsafeN/A
MDXComponents/HeadForbiddenForbiddenTechnical component used to assign metadata (generally for SEO purpose) to the current MDX document
MDXPageUnsafeUnsafeN/A
NavbarUnsafeUnsafeN/A
Navbar/ColorModeToggleUnsafeUnsafeN/A
Navbar/ContentUnsafeUnsafeN/A
Navbar/LayoutUnsafeUnsafeN/A
Navbar/LogoUnsafeUnsafeN/A
Navbar/MobileSidebarUnsafeUnsafeN/A
Navbar/MobileSidebar/HeaderUnsafeUnsafeN/A
Navbar/MobileSidebar/LayoutUnsafeUnsafeN/A
Navbar/MobileSidebar/PrimaryMenuUnsafeUnsafeN/A
Navbar/MobileSidebar/SecondaryMenuUnsafeUnsafeN/A
Navbar/MobileSidebar/ToggleUnsafeUnsafeN/A
Navbar/SearchUnsafeUnsafeN/A
NavbarItemUnsafeUnsafeN/A
NavbarItem/DefaultNavbarItemUnsafeUnsafeN/A
NavbarItem/DocNavbarItemUnsafeUnsafeN/A
NavbarItem/DocSidebarNavbarItemUnsafeUnsafeN/A
NavbarItem/DocsVersionDropdownNavbarItemUnsafeUnsafeN/A
NavbarItem/DocsVersionNavbarItemUnsafeUnsafeN/A
NavbarItem/DropdownNavbarItemUnsafeUnsafeN/A
NavbarItem/HtmlNavbarItemUnsafeUnsafeN/A
NavbarItem/LocaleDropdownNavbarItemUnsafeUnsafeN/A
NavbarItem/NavbarNavLinkUnsafeUnsafeN/A
NavbarItem/SearchNavbarItemUnsafeUnsafeN/A
PaginatorNavLinkUnsafeUnsafeN/A
SearchMetadataUnsafeUnsafeN/A
SiteMetadataUnsafeUnsafeN/A
SkipToContentUnsafeUnsafeN/A
TOCUnsafeUnsafeN/A
TOCCollapsibleUnsafeUnsafeN/A
TOCCollapsible/CollapseButtonUnsafeUnsafeN/A
TOCInlineUnsafeUnsafeN/A
TOCItemsUnsafeUnsafeN/A
TOCItems/TreeUnsafeUnsafeN/A
TabItemUnsafeUnsafeN/A
TabsUnsafeUnsafeN/A
TagUnsafeUnsafeN/A
TagsListByLetterUnsafeUnsafeN/A
TagsListInlineUnsafeUnsafeN/A
ThemedImageUnsafeUnsafeN/A

Components available for swizzle in @docusaurus/plugin-debug:

Component nameWrapEjectDescription
DebugConfigUnsafeUnsafeN/A
DebugContentUnsafeUnsafeN/A
DebugGlobalDataUnsafeUnsafeN/A
DebugJsonViewUnsafeUnsafeN/A
DebugLayoutUnsafeUnsafeN/A
DebugRegistryUnsafeUnsafeN/A
DebugRoutesUnsafeUnsafeN/A
DebugSiteMetadataUnsafeUnsafeN/A

Swizzle actions:

ActionsCLI optionDescription
Wrap--wrapCreates a wrapper around the original theme component. Allows rendering other components before/after the original theme component. Tip: prefer --wrap whenever possible to reduce the amount of code to maintain.
Eject--ejectEjects the full source code of the original theme component. Allows overriding of the original component entirely with your own UI and logic. Tip: --eject can be useful for completely redesigning a component.

Swizzle safety statuses:

StatusCLI optionDescription
SafeThis component is safe to swizzle and was designed for this purpose. The swizzled component is retro-compatible with minor version upgrades.
Unsafe--dangerThis component is unsafe to swizzle, but you can still do it! Warning: we may release breaking changes within minor version upgrades. You will have to upgrade your component manually and maintain it over time. Tip: your customization can't be done in a Safe way? [https://github.com/facebook/docusaurus/discussions/5468]
ForbiddenThis component is not meant to be swizzled.

See the swizzle guide for more info.

New Projects​

Create and start​

Create a new Docusaurus site and then start the site:

npx create-docusaurus@latest my-website classic
cd my-website
npx docusaurus start

New project structure​

Assuming you used the setup like the above, then you will get the following directory structure:

my-website
├── blog
|   ├── 2019-05-28-hola.md
|   ├── 2019-05-29-hello-world.md
|   └── 2020-05-30-welcome.md
├── docs
|   ├── doc1.md
|   ├── doc2.md
|   ├── doc3.md
|   └── mdx.md
├── src
|   ├── css
|   |   └── custom.css
|   └── pages
|       ├── styles.module.css
|       └── index.js
├── static
|   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock
  • /blog/ - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the path option. More details can be found in the blog guide
  • /docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the path option. More details can be found in the docs guide
  • /src/ - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
    • /src/pages - Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the pages guide
  • /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory
  • /docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1
  • /package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them
  • /sidebars.js - Used by the documentation to specify the order of documents in the sidebar

Existing Projects​

Updating Docusaurus version​

You can manually change the version number in package.json to the desired version. Note that all @docusaurus/-namespaced packages should be using the same version.

package.json
{
  "dependencies": {
    "@docusaurus/core": "2.0.0-beta.22",
    "@docusaurus/preset-classic": "2.0.0-beta.22",
    // ...
  }
}

Then, in the directory containing package.json, run your package manager's install command, and then check to make sure the update occurred successfully (you should see the correct version as output in the second command):

npm install
npx docusaurus --version

Configuration​

Site configuration details are stored in the docusaurus.config.js file at the root level of your Docusaurus site directory. The high-level overview of Docusaurus configuration can be categorized as follows:

Site metadata​

Site metadata contains the essential global metadata such as title, url, baseUrl, and favicon. They are used in several places such as your site's title and headings, browser tab icon, social sharing (Facebook, Twitter) information or even to generate the correct path to serve your static files.

Deployment configurations​

Deployment configurations such as projectName, organizationName, and optionally deploymentBranch are used when you deploy your site with the deploy command. It is recommended to check the deployment docs for more information.

Theme, plugin, and preset configurations​

List the themes, plugins, and presets for your site in the themes, plugins, and presets fields, respectively. These are typically npm packages:

docusaurus.config.js
module.exports = {
  // ...
  plugins: [
    '@docusaurus/plugin-content-blog',
    '@docusaurus/plugin-content-pages',
  ],
  themes: ['@docusaurus/theme-classic'],
};

See the using plugins guide for more information and help.

Custom configurations​

Docusaurus guards docusaurus.config.js from unknown fields. To add custom fields, define them in customFields. For example:

docusaurus.config.js
module.exports = {
  // ...
  customFields: {
    image: '',
    keywords: [],
  },
  // ...
};

Access Docusaurus configuration from components​

Your configuration object, customFields, as well as all other Docusaurus configuration details will be made available to all the components of your site. And you may access them via React context as siteConfig. Basic example:

import React from 'react';
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

const Hello = () => {
  const {siteConfig} = useDocusaurusContext();
  console.log(JSON.stringify(siteConfig, null, 2));
  const {title, tagline} = siteConfig;

  return <div>{`${title} · ${tagline}`}</div>;
};

A sample siteConfig logged to the console appears below for inspection.

Sample configuration object
{
  "siteConfig": {
    "title": "Handbook",
    "tagline": "Software engineering handbooks are cool",
    "url": "https://dwf.netlify.app",
    "baseUrl": "/",
    "onBrokenLinks": "throw",
    "onBrokenMarkdownLinks": "warn",
    "favicon": "img/favicon.ico",
    "organizationName": "facebook",
    "projectName": "docusaurus",
    "customFields": {
      "things": {
        "something": "Whaaaa"
      }
    },
    "i18n": {
      "defaultLocale": "en",
      "locales": [
        "en"
      ],
      "path": "i18n",
      "localeConfigs": {}
    },
    "presets": [
      [
        "classic",
        {
          "docs": {
            "sidebarPath": "/Volumes/DWF/D/development-and-engineering/software-development-handbook/sidebars.js",
            "editUrl": "https://github.com/farlowdw/software-development-handbook/tree/master/",
            "remarkPlugins": [
              null
            ],
            "rehypePlugins": [
              [
                null,
                {
                  "throwOnError": true,
                  "globalGroup": true,
                  "macros": {
                    "\\x": "x+1"
                  }
                }
              ]
            ],
            "showLastUpdateTime": true
          },
          "blog": {
            "showReadingTime": true,
            "editUrl": "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
            "remarkPlugins": [
              null
            ],
            "rehypePlugins": [
              [
                null,
                {
                  "throwOnError": true,
                  "globalGroup": true,
                  "macros": {
                    "\\x": "x+1"
                  }
                }
              ]
            ],
            "blogTitle": "My Blog Title",
            "sortPosts": "ascending"
          },
          "theme": {
            "customCss": "/Volumes/DWF/D/development-and-engineering/software-development-handbook/src/css/custom.scss"
          },
          "pages": {
            "rehypePlugins": [
              [
                null,
                {
                  "throwOnError": true,
                  "globalGroup": true,
                  "macros": {
                    "\\x": "x+1"
                  }
                }
              ]
            ]
          }
        }
      ]
    ],
    "stylesheets": [
      {
        "href": "https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css",
        "type": "text/css",
        "integrity": "sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM",
        "crossorigin": "anonymous"
      },
      {
        "href": "https://cdn.jsdelivr.net/npm/pseudocode@latest/build/pseudocode.min.css"
      }
    ],
    "scripts": [
      {
        "src": "https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.js",
        "async": true
      },
      {
        "src": "https://cdn.jsdelivr.net/npm/pseudocode@latest/build/pseudocode.min.js",
        "async": true
      }
    ],
    "plugins": [
      "docusaurus-plugin-sass",
      "/Volumes/DWF/D/development-and-engineering/software-development-handbook/node_modules/docusaurus-plugin-image-zoom/src/index.js"
    ],
    "themeConfig": {
      "colorMode": {
        "defaultMode": "dark",
        "disableSwitch": false,
        "respectPrefersColorScheme": false
      },
      "docs": {
        "sidebar": {
          "hideable": true,
          "autoCollapseCategories": false
        },
        "versionPersistence": "localStorage"
      },
      "tableOfContents": {
        "minHeadingLevel": 2,
        "maxHeadingLevel": 5
      },
      "navbar": {
        "title": "Software Engineering Handbook",
        "logo": {
          "alt": "Software Engineering Handbook Logo",
          "src": "img/logo.svg"
        },
        "items": [
          {
            "to": "/docs/intro",
            "label": "Handbook",
            "position": "left",
            "activeBaseRegex": "/docs/"
          },
          {
            "to": "/blog",
            "label": "Blog",
            "position": "left"
          },
          {
            "href": "https://github.com/facebook/docusaurus",
            "label": "GitHub",
            "position": "right"
          }
        ],
        "hideOnScroll": false
      },
      "footer": {
        "style": "dark",
        "links": [
          {
            "title": "Docs",
            "items": [
              {
                "label": "Tutorial",
                "to": "/docs/intro"
              }
            ]
          },
          {
            "title": "Community",
            "items": [
              {
                "label": "Stack Overflow",
                "href": "https://stackoverflow.com/questions/tagged/docusaurus"
              },
              {
                "label": "Discord",
                "href": "https://discordapp.com/invite/docusaurus"
              },
              {
                "label": "Twitter",
                "href": "https://twitter.com/docusaurus"
              }
            ]
          },
          {
            "title": "More",
            "items": [
              {
                "label": "Blog",
                "to": "/blog"
              },
              {
                "label": "GitHub",
                "href": "https://github.com/facebook/docusaurus"
              }
            ]
          }
        ],
        "copyright": "Copyright © 2022 My Project, Inc. Built with Docusaurus."
      },
      "zoom": {
        "selector": ".markdown :not(em) > img",
        "config": {
          "background": "rgb(50, 50, 50)"
        }
      },
      "prism": {
        "theme": {
          "plain": {
            "color": "#393A34",
            "backgroundColor": "#f6f8fa"
          },
          "styles": [
            {
              "types": [
                "comment",
                "prolog",
                "doctype",
                "cdata"
              ],
              "style": {
                "color": "#999988",
                "fontStyle": "italic"
              }
            },
            {
              "types": [
                "namespace"
              ],
              "style": {
                "opacity": 0.7
              }
            },
            {
              "types": [
                "string",
                "attr-value"
              ],
              "style": {
                "color": "#e3116c"
              }
            },
            {
              "types": [
                "punctuation",
                "operator"
              ],
              "style": {
                "color": "#393A34"
              }
            },
            {
              "types": [
                "entity",
                "url",
                "symbol",
                "number",
                "boolean",
                "variable",
                "constant",
                "property",
                "regex",
                "inserted"
              ],
              "style": {
                "color": "#36acaa"
              }
            },
            {
              "types": [
                "atrule",
                "keyword",
                "attr-name",
                "selector"
              ],
              "style": {
                "color": "#00a4db"
              }
            },
            {
              "types": [
                "function",
                "deleted",
                "tag"
              ],
              "style": {
                "color": "#d73a49"
              }
            },
            {
              "types": [
                "function-variable"
              ],
              "style": {
                "color": "#6f42c1"
              }
            },
            {
              "types": [
                "tag",
                "selector",
                "keyword"
              ],
              "style": {
                "color": "#00009f"
              }
            }
          ]
        },
        "darkTheme": {
          "plain": {
            "color": "#F8F8F2",
            "backgroundColor": "#282A36"
          },
          "styles": [
            {
              "types": [
                "prolog",
                "constant",
                "builtin"
              ],
              "style": {
                "color": "rgb(189, 147, 249)"
              }
            },
            {
              "types": [
                "inserted",
                "function"
              ],
              "style": {
                "color": "rgb(80, 250, 123)"
              }
            },
            {
              "types": [
                "deleted"
              ],
              "style": {
                "color": "rgb(255, 85, 85)"
              }
            },
            {
              "types": [
                "changed"
              ],
              "style": {
                "color": "rgb(255, 184, 108)"
              }
            },
            {
              "types": [
                "punctuation",
                "symbol"
              ],
              "style": {
                "color": "rgb(248, 248, 242)"
              }
            },
            {
              "types": [
                "string",
                "char",
                "tag",
                "selector"
              ],
              "style": {
                "color": "rgb(255, 121, 198)"
              }
            },
            {
              "types": [
                "keyword",
                "variable"
              ],
              "style": {
                "color": "rgb(189, 147, 249)",
                "fontStyle": "italic"
              }
            },
            {
              "types": [
                "comment"
              ],
              "style": {
                "color": "rgb(98, 114, 164)"
              }
            },
            {
              "types": [
                "attr-name"
              ],
              "style": {
                "color": "rgb(241, 250, 140)"
              }
            }
          ]
        },
        "magicComments": [
          {
            "className": "theme-code-block-highlighted-line",
            "line": "highlight-next-line",
            "block": {
              "start": "highlight-start",
              "end": "highlight-end"
            }
          },
          {
            "className": "code-block-error-line",
            "line": "highlight-error-next-line"
          }
        ],
        "additionalLanguages": [
          "apacheconf",
          "applescript",
          "asciidoc",
          "aspnet",
          "awk",
          "bash",
          "basic",
          "c",
          "clojure",
          "cpp",
          "csharp",
          "css",
          "csv",
          "django",
          "docker",
          "editorconfig",
          "ejs",
          "elixir",
          "erlang",
          "excel-formula",
          "flow",
          "fortran",
          "git",
          "go",
          "go-module",
          "graphql",
          "handlebars",
          "http",
          "java",
          "javadoclike",
          "javascript",
          "js-extras",
          "jsdoc",
          "json",
          "jsonp",
          "jsx",
          "latex",
          "less",
          "lisp",
          "log",
          "lua",
          "makefile",
          "markdown",
          "markup",
          "markup-templating",
          "mermaid",
          "mongodb",
          "nginx",
          "perl",
          "php",
          "php-extras",
          "phpdoc",
          "plsql",
          "powerquery",
          "powershell",
          "pug",
          "python",
          "r",
          "regex",
          "ruby",
          "rust",
          "sas",
          "sass",
          "scheme",
          "scss",
          "shell-session",
          "sql",
          "systemd",
          "toml",
          "tsx",
          "turtle",
          "typescript",
          "vim",
          "visual-basic",
          "wasm",
          "wiki",
          "wolfram",
          "yaml"
        ]
      },
      "metadata": []
    },
    "baseUrlIssueBanner": true,
    "onDuplicateRoutes": "warn",
    "staticDirectories": [
      "static"
    ],
    "themes": [],
    "clientModules": [],
    "titleDelimiter": "|",
    "noIndex": false
  },
  "siteMetadata": {
    "docusaurusVersion": "2.0.0-beta.22",
    "siteVersion": "0.0.0",
    "pluginVersions": {
      "docusaurus-plugin-content-docs": {
        "type": "package",
        "name": "@docusaurus/plugin-content-docs",
        "version": "2.0.0-beta.22"
      },
      "docusaurus-plugin-content-blog": {
        "type": "package",
        "name": "@docusaurus/plugin-content-blog",
        "version": "2.0.0-beta.22"
      },
      "docusaurus-plugin-content-pages": {
        "type": "package",
        "name": "@docusaurus/plugin-content-pages",
        "version": "2.0.0-beta.22"
      },
      "docusaurus-plugin-debug": {
        "type": "package",
        "name": "@docusaurus/plugin-debug",
        "version": "2.0.0-beta.22"
      },
      "docusaurus-theme-classic": {
        "type": "package",
        "name": "@docusaurus/theme-classic",
        "version": "2.0.0-beta.22"
      },
      "docusaurus-plugin-sass": {
        "type": "package",
        "name": "docusaurus-plugin-sass",
        "version": "0.2.2"
      },
      "docusaurus-plugin-image-zoom": {
        "type": "package",
        "name": "docusaurus-plugin-image-zoom",
        "version": "0.1.1"
      }
    }
  },
  "globalData": {
    "docusaurus-plugin-content-docs": {
      "default": {
        "path": "/docs",
        "versions": [
          {
            "name": "current",
            "label": "Next",
            "isLast": true,
            "path": "/docs",
            "mainDocId": "intro",
            "docs": [
              {
                "id": "books/algorithm-design-manual/book-notes",
                "path": "/docs/books/algorithm-design-manual/book-notes",
                "sidebar": "docs"
              },
              {
                "id": "books/algorithm-design-manual/exercises-and-solutions",
                "path": "/docs/books/algorithm-design-manual/exercises-and-solutions",
                "sidebar": "docs"
              },
              {
                "id": "books/algorithm-design-manual/index",
                "path": "/docs/books/algorithm-design-manual",
                "sidebar": "docs"
              },
              {
                "id": "books/algorithm-design-manual/lecture-notes",
                "path": "/docs/books/algorithm-design-manual/lecture-notes",
                "sidebar": "docs"
              },
              {
                "id": "intro",
                "path": "/docs/intro",
                "sidebar": "docs"
              },
              {
                "id": "reference/css/css-diner",
                "path": "/docs/reference/css/css-diner",
                "sidebar": "docs"
              },
              {
                "id": "reference/css/index",
                "path": "/docs/css",
                "sidebar": "docs"
              },
              {
                "id": "reference/docusaurus/documentation-notes",
                "path": "/docs/reference/docusaurus/documentation-notes",
                "sidebar": "docs"
              },
              {
                "id": "reference/docusaurus/features",
                "path": "/docs/reference/docusaurus/features",
                "sidebar": "docs"
              },
              {
                "id": "reference/docusaurus/index",
                "path": "/docs/reference/docusaurus/",
                "sidebar": "docs"
              },
              {
                "id": "reference/docusaurus/katex",
                "path": "/docs/reference/docusaurus/katex",
                "sidebar": "docs"
              },
              {
                "id": "reference/docusaurus/templates",
                "path": "/docs/reference/docusaurus/templates",
                "sidebar": "docs"
              },
              {
                "id": "tutorial-basics/congratulations",
                "path": "/docs/tutorial-basics/congratulations"
              },
              {
                "id": "tutorial-basics/create-a-blog-post",
                "path": "/docs/tutorial-basics/create-a-blog-post"
              },
              {
                "id": "tutorial-basics/create-a-document",
                "path": "/docs/tutorial-basics/create-a-document"
              },
              {
                "id": "tutorial-basics/create-a-page",
                "path": "/docs/tutorial-basics/create-a-page"
              },
              {
                "id": "tutorial-basics/deploy-your-site",
                "path": "/docs/tutorial-basics/deploy-your-site"
              },
              {
                "id": "tutorial-basics/markdown-features",
                "path": "/docs/tutorial-basics/markdown-features"
              },
              {
                "id": "tutorial-extras/manage-docs-versions",
                "path": "/docs/tutorial-extras/manage-docs-versions"
              },
              {
                "id": "tutorial-extras/translate-your-site",
                "path": "/docs/tutorial-extras/translate-your-site"
              },
              {
                "id": "/category/books",
                "path": "/docs/category/books",
                "sidebar": "docs"
              },
              {
                "id": "/category/reference",
                "path": "/docs/category/reference",
                "sidebar": "docs"
              }
            ],
            "draftIds": [],
            "sidebars": {
              "docs": {
                "link": {
                  "path": "/docs/intro",
                  "label": "intro"
                }
              }
            }
          }
        ],
        "breadcrumbs": true
      }
    }
  },
  "i18n": {
    "defaultLocale": "en",
    "locales": [
      "en"
    ],
    "path": "i18n",
    "currentLocale": "en",
    "localeConfigs": {
      "en": {
        "label": "English",
        "direction": "ltr",
        "htmlLang": "en",
        "calendar": "gregory",
        "path": "en"
      }
    }
  },
  "codeTranslations": {}
}

Babel Configuration​

For new Docusaurus projects, we automatically generated a babel.config.js in the project root.

babel.config.js
module.exports = {
  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
};

Most of the time, this configuration will work just fine. If you want to customize your Babel configuration (e.g., to add support for Flow), you can directly edit this file. For your changes to take effect, you need to restart the Docusaurus dev server.

Guides​

Pages​

Caveats​

The @docusaurus/plugin-content-pages plugin empowers you to create one-off standalone pages like a showcase page, playground page, or support page. You can use React components or Markdown (hence, file extensions .js, .jsx, .md, and mdx are all valid). Note that Pages do not have sidebars (only docs do). Check the link above for a more exhaustive list of options for what you can do with Pages.

Each page doesn't come with any styling. You will need to import the Layout component from @theme/Layout and wrap your contents within that component if you want the navbar and/or footer to appear. (See the source code for the Layout component if desired.)

Routing behavior is similar to other static site generators (e.g., Jekyll and Next). Any JavaScript file you create under the /src/pages/ directory will be automatically converted to a website page following the /src/pages/ directory hierarchy. For example:

  • /src/pages/index.js → [baseUrl]
  • /src/pages/foo.js → [baseUrl]/foo
  • /src/pages/foo/test.js → [baseUrl]/foo/test
  • /src/pages/foo/index.js → [baseUrl]/foo/

Creating pages​

Anything created in the /src/pages directory will be a standalone page.

In this component-based development era, it is encouraged to co-locate your styling, markup, and behavior together into components. Each page is a component, and if you need to customize your page design with your own styles, we recommend co-locating your styles with the page component in its own directory. For example, to create a "Support" page, you could do one of the following:

  • Add a /src/pages/support.js file
  • Create a /src/pages/support/ directory and a /src/pages/support/index.js file.

The latter is preferred as it has the benefits of letting you put files related to the page within that directory. For example, a CSS module file (styles.module.css) with styles meant to only be used on the "Support" page. Note that this is merely a recommended directory structure, and you will still need to manually import the CSS module file within your component module (support/index.js).

Omitting routes for files and folders​

By default, any Markdown or JavaScript file starting with _ will be ignored and no routes will be created for that file (see the exclude option). The same is true for directories.

Duplicate routes​

You may accidentally create multiple pages that are meant to be accessed on the same route. When this happens, Docusaurus will warn you about duplicate routes when you run yarn start or yarn build, but the site will still be built successfully. The page that was created last will be accessible, but it will override other conflicting pages. To resolve this issue, you should modify or remove any conflicting routes.

Docs​

The docs feature provides users with a way to organize Markdown files in a hierarchical format. Check the Docs Plugin API Reference documentation for an exhaustive list of options.

Default docs and blog structure​

A freshly initialized Docusaurus site has the following structure:

example.com/                                -> generated from `src/pages/index.js`

example.com/docs/intro                      -> generated from `docs/intro.md`
example.com/docs/tutorial-basics/...        -> generated from `docs/tutorial-basics/...`
...

example.com/blog/2021/08/26/welcome         -> generated from `blog/2021-08-26-welcome/index.md`
example.com/blog/2021/08/01/mdx-blog-post   -> generated from `blog/2021-08-01-mdx-blog-post.mdx`
...

Markdown front matter​

See the API documentation for all possible fields. The front matter is not necessary, but it should be used when possible.

Doc tags​

Optionally, you can add tags to your doc pages, which introduces another dimension of categorization in addition to the docs sidebar. Tags are passed in the front matter as a list of labels:

Tags can also be declared with tags: [Demo, Getting started]. Read more about all the possible Yaml array syntaxes.

Document IDs​

Every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory. For example, the ID of greeting.md is greeting, and the ID of guide/hello.md is guide/hello.

website # Root directory of your site
└── docs
   ├── greeting.md
   └── guide
      └── hello.md

However, the last part of the id can be defined by the user in the front matter. For example, if guide/hello.md's content is defined as below, its final id is guide/part1.

---
id: part1
---

Lorem ipsum

The ID is used to refer to a document when hand-writing sidebars, or when using docs-related layout components or hooks.

Doc URLs and slug​

By default, a document's URL location is its file path relative to the docs folder. Use the slug front matter to change a document's URL. For example, suppose your site structure looks like this:

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

By default, hello.md will be available at /docs/guide/hello. You can change its URL location to /docs/bonjour:

---
slug: /bonjour
---

Lorem ipsum

slug will be appended to the doc plugin's routeBasePath, which is /docs by default. See Docs-only mode for how to remove the /docs part from the URL.

Note that it is possible to use:

  • absolute slugs: slug: /mySlug, slug: /...
  • relative slugs: slug: mySlug, slug: ./../mySlug...

If you want a document to be available at the root, and have a path like https://docusaurus.io/docs/, you can use the slug front matter:

---
id: my-home-doc
slug: /
---

Lorem ipsum

Here's a summary of what kind of type of sidebar items are available, namely an item like the following for an example:

type SidebarItemDoc =
  // Normal syntax
  | {
      type: 'doc';
      id: string;
      label: string; // Sidebar label text
      className?: string; // Class name for sidebar label
      customProps?: Record<string, unknown>; // Custom props
    }

  // Shorthand syntax
  | string; // docId shortcut
  • Doc: link to a doc page, associating it with the sidebar
  • Link: link to any internal or external page
  • Category: creates a dropdown of sidebar items
  • Autogenerated: generate a sidebar slice automatically
  • HTML: renders pure HTML in the item's position
  • *Ref: link to a doc page, without making the item take part in navigation generation

Blog​

Options​

Check the Blog Plugin API Reference documentation for an exhaustive list of options when using the blog capabilities that come along with Docusaurus.

Front matter​

See the Markdown front matter reference for all options that can be used with blog posts.

Blog list and truncated summaries​

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

Everything here will be part of the blog post summary.

Even this.

<!--truncate-->

But anything from here on down will not be.

Not this.

Or this.

I can conveniently use Docusaurus green everywhere!