Skip to main content

docusaurus ↔ React Framework SSG CMS for API docs as SPA with built-in Routing + MDX support

Source: docusaurus.io/

aka docusaurus, docu, DS

docusaurus features

!use @docusaurus for v2+ & NOT abandonware docusaurus on npm!

req swizzle to customize?!​

req Swizzling to reconfig certain UI - to eject theme under new dir src/theme to customize - pain in the A!

Source: docusaurus.io/docs/swizzling

react-markdown​

React Lib FC Wrapper to render MDX extends with plugins

[<span data-tooltip-id="preview__nH4Xzf6gaWHnNrkHr">docusaurus</span>](docusaurus) \> redoc on github

Docusaurus API

Docusaurus MDX Syntax

Docusaurus concepts

docusaurus pain fixes

create-docusaurus​

to scaffold new docusaurus project

docusaurus.config.js

Admonitions Callout Blocks​

where is styling for :::tip and :::danger :::caution defined?! - Callout blocks to draw extra attention to specific concepts

Source: quarto.org/docs/authoring/callouts.html

"docusaurus

If your dependency management bot wants to upgrade to React 18 for you, and it doesn't cause any problems (around peer dependencies), feel free to accept it."
The most urgent blocking issue is that MDX v1 doesn't declare React v18 in its peer dependencies range. Because the v1 line is effectively frozen, I believe there's no plan to fix this. Certain package managers (namely, npm v7 and pnpm) are strict about peer dependencies and will refuse to install properly if @mdx-js/react is installed alongside react@18. This will be confusing for the users, so it's another strong point why we'll delay it to v3: we'll only migrate to MDX v2 in Docusaurus v3 (#4029).

Source: github.com/facebook/docusaurus/issues/7264

References​

  1. docusaurus-theme-search-typesense ↔ typesense Search UI FC docu plugin for docusaurus

  2. docs file-based routing ↔ DS will match dir & md to url slug - dir hierachy maps to _localhost/docs/path/to/dir-of-md/dir-of-md.md - BUT different for /docs & /blog

  3. src/components/HomepageFeatures/index.tsx ↔ docusaurus FC for root home page (classic preset)

  4. docu plugin ↔ to extend docusaurus with new feat

  5. webpackbar ↔ CLI loading bar animation for webpack - used in docusaurus

  6. SSG over ISR for docs ↔ When starting this project, I was largely torn over whether to go with Next.js+Nextra vs docusaurus. Now, with the full experience of deploying this website, I can properly discuss the tradeoffs and lessons learned from going with Docusaurus over Nextra. [WRITING IN PROGRESS][ADD SOME PICTURES!]