Build book-like internationalized, indexed, searcheable websites using React made easy
This is a hands-on deep-dive introduction to installing and using Docusaurus as a static (JAM stack) website builder.
NOTE: Content here are my personal opinions, and not intended to represent any employer (past or present). “PROTIP:” here highlight information I haven’t seen elsewhere on the internet because it is hard-won, little-know but significant facts based on my personal research and experience.
Docusauraus2 provides several features not provided by GitHub Pages:
- Layout using React Redux MDX rather than static markdown
- Document versioning
- Content Search (using Algolia service)
- Translations (Internationalization, abbreviated as “i18n”)
Searcheable Table in a sample Docusaurus (React) site
This takes advantage of React, not possible with plain static GitHub Markdown alone.
NOTE that Docusaurus does not support Windows IE11 (Internet Explorer).
Docusaurus is not just for documentation websites.
Docusaurus was created and now maintained by Facebook, as a free open-source resource.
22-07-09 had 326 watchers and 34,700 Stars
21-03-19 had 264 watchers and 22,400 Stars
Evaluate the repo for due diligence.
At time of writing, there are 192 issues and 1315 closed.
The oldest open issue goes back to May 5, 2018.
21 authors have pushed 35 commits to master and 68 commits to all branches.
Sebastien Lorber is the major contributor and owner, a contractor at Facebook. His personal website https://sebastienlorber.com has an icon to switch between dark and light themes.
<a target=”_blank” href=”https://twitter.com/docusaurus
Docusaurus1 began in 2017. It now has 2,438 Followers.
On Mar 9, 2021 “Docusaurus2 now has full feature parity with v1”
So stay away from version 1 documentation at
“We created Docusaurus … provide a consistent look and feel across all our open source projects”.
Trend of weekly downloads and reviews in OpenBase.com
Who’s using Docusaurus?
What some Docusaurus-based sites look like.
Support Docusaurus financially.
View Sample Online
It’s an online sandbox, showing the same site contents as after local install below:
v2 local install
There are two ways to get started:
A. npm package
B. docusaurus-init package. That’s what this site describes.
Navigate to or create a container folder for your GitHub account where a new folder will be created by init program. The example here is:
Where gmail_acct is the GitHub organization account I use, “Supersite” is the name of the repo and fake product name.
PROTIP: I would like to have the documentation in the “Docs” folder to travel with the app’s source code.
Generate scaffold after changing DOC_SITE_NAME value:
DOC_SITE_NAME="Supersite" DOC_TEMPLATE="classic" npx @docusaurus/init@latest init "$DOC_SITE_NAME" "$DOC_TEMPLATE"
Type “y” to answer:
Need to install the following packages: @docusaurus/init@latest Ok to proceed? (y) y
Navigate into generated:
cd $DOC_SITE_NAME pwd
For me, I’m at
See folders generated:
cd docs tree -L 2
├── README.md ├── babel.config.js ├── blog ├── docs ├── docusaurus.config.js ├── node_modules ├── package.json ├── sidebars.js ├── src ├── static └── yarn.lock
View site locally
Start the development server:
yarn run start
npx docusaurus start
The above command opens on your default browser
Back on the CLI, no other commands can be added until you press control+C to cancel the localhost running.
Below is a correspondance of the documentation and visuals associated with files:
|docusaurus.config.js (formerly siteConfig.js)||the "start" in CLI command "run start"||scripts invoked by the NodeJs package manager.|
|docs folder||Docs menu on init page|| where you add your markdown that represents your documentation. Files:
create-a-blog-post.md create-a-document.md create-a-page.md getting-started.md markdown-features.mdx thank-you.md
|blogs folder||Blog menu on init page|| where you add your markdown for your dated blog posts. Files:
2019-05-28-hola.md 2019-05-29-hello-world.md 2019-05-30-welcome.md
|build folder||not displayed||minified js assets, html, etc. served to users, created by yarn build: 404.html, assets, blog, docs, img, index.html, markdown-page, sitemap.xml|
|package.json||Text editor||List of NodeJs modules to be downloaded into node_modules folderl|
|node_modules||not displayed||holds folders of libraries NodeJs downloads|
|sidebars.js (formerly sidebars.json)||not displayed||where you maintain the layout and content of the sidebar (left-side menu)|
|src folder||Within a text editor|| index.js is what NodeJs invokes to load React.js, the "brains" of Docusauraus. css files define the layout. Files:
src ├── css │ └── custom.css └── pages ├── index.js ├── markdown-page.md └── styles.module.css
|static/img||Referenced in html & css|| static images. Files:
docusaurus.png favicon.ico logo.svg undraw_docusaurus_mountain.svg undraw_docusaurus_react.svg undraw_docusaurus_tree.svgThese get built into the build/img folder.
https://v2.docusaurus.io/docs/docusaurus.config.js lists each configuration item.
Add the domain name that you obtained for your site:
This setting updates the GitHub Pages Custom domain entered in the GitHub repo’s settings. Without that line, the setting is cleared from GitHub’s GUI on every build.
Code Sortable Tables
Code theme styling
Add Content Search
Generate html static files
List files, then build:
ls -al yarn build
[en] Creating an optimized production build... ✔ Client Compiled successfully in 10.57s ✔ Server Compiled successfully in 12.26s Success! Generated static files in build. Use `npm run serve` to test your build locally. ✨ Done in 16.98s.
List files, then build:
ls -al build npm run serve ls -al
Publish to GitHub
More on front-end software development
This is one of several topics:
- UI Design Systems
- Text Editors
- Markdown text for GitHub from HTML
- Front-end UI creation options
- Docusaurus static website generator
- Static websites
- JAM Stack Website Project Plan
- Jekyll Site Development
- Website styles
- Website Styling
- Email from website
- Search within Hyde format Jekyll websites
- Data Visualization using Tableau