Wilson Mar bio photo

Wilson Mar


Calendar YouTube Github


Build book-like internationalized, indexed, searcheable websites using React made easy

US (English)   Norsk (Norwegian)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Estonian   اَلْعَرَبِيَّةُ (Egypt Arabic)   Napali   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean


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.

  1. Visit https://v2.docusaurus.io

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

  2. https://pester.dev/docs/additional-resources/articles

    Searcheable Table in a sample Docusaurus (React) site

    This takes advantage of React, not possible with plain static GitHub Markdown alone.

  3. https://v2.docusaurus.io/docs

    NOTE that Docusaurus does not support Windows IE11 (Internet Explorer).

    Docusaurus is not just for documentation websites.

    Due Diligence

  4. https://github.com/facebook/docusaurus

    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

  5. https://github.com/facebook/docusaurus/issues

    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.

  6. https://github.com/facebook/docusaurus/pulse

    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.

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

  8. (Based on https://v2.docusaurus.io/blog/2017/12/14/introducing-docusaurus)

    “We created Docusaurus … provide a consistent look and feel across all our open source projects”.

  9. https://openbase.com/js/docusaurus

    Trend of weekly downloads and reviews in OpenBase.com

  10. https://stackshare.io/docusaurus

    Who’s using Docusaurus?

  11. https://v2.docusaurus.io/showcase

    What some Docusaurus-based sites look like.

  12. https://v2.docusaurus.io/blog

  13. https://v2.docusaurus.io/docs/design-principles

  14. https://opencollective.com/docusaurus#category-BUDGET

    Support Docusaurus financially.

    View Sample Online

  15. https://new.docusaurus.io refers you to

    It’s an online sandbox, showing the same site contents as after local install below:


    v2 local install

  16. https://v2.docusaurus.io/docs/installation

    There are two ways to get started:

    A. npm package

    B. docusaurus-init package. That’s what this site describes.

  17. Install NodeJs

  18. Install Yarn

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

  20. Generate scaffold after changing DOC_SITE_NAME value:

    npx @docusaurus/init@latest init "$DOC_SITE_NAME" "$DOC_TEMPLATE"
  21. Type “y” to answer:

    Need to install the following packages:
    Ok to proceed? (y) y   
  22. Navigate into generated:


    For me, I’m at

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

  24. 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:

Folder /File Visual Description
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:
blogs folder Blog menu on init page where you add your markdown for your dated blog posts. Files:
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:
├── css
│   └── custom.css
└── pages
    ├── index.js
    ├── markdown-page.md
    └── styles.module.css
static/img Referenced in html & css static images. Files:
These get built into the build/img folder.

Configure docusaurus.config.js

  1. https://v2.docusaurus.io/docs/docusaurus.config.js

  2. https://v2.docusaurus.io/docs/docusaurus.config.js lists each configuration item.


    Configure cname

  3. Add the domain name that you obtained for your site:

    cname: 'docs.mydomain.com',

    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

  4. https://docs.theochu.com/docusaurus/sortable-tables

    Code theme styling

  5. https://v2.docusaurus.io/docs/api/themes

  6. https://docs.theochu.com/docusaurus/styling/

  7. https://docusaurus-template-no-style.netlify.app

  8. https://docs.theochu.com/docusaurus/search

    Add plug-ins

  9. https://v2.docusaurus.io/docs/api/plugins


  10. https://docusaurus.io/docs/en/translation

    via CrowdIn.

    Generate html static files

  11. 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.
  12. List files, then build:

    ls -al build
    npm run serve
    ls -al

    Publish to GitHub

    yarn deploy



More on front-end software development

This is one of several topics:

  1. UI Design Systems
  2. Text Editors
  3. Markdown text for GitHub from HTML
  4. 508 Accessibility

  5. gRPC (g___ Remote Procedure Call)
  6. HTTP/2 Transition Project Plan

  7. Front-end UI creation options
  8. Docusaurus static website generator
  9. Static websites
  10. JAM Stack Website Project Plan
  11. Jekyll Site Development
  12. Gatsby app generator

  13. Website styles
  14. Website Styling
  15. VueJs front-end framework

  16. Protractor to automate testing of Angular and other web pages

  17. Email from website
  18. Search within Hyde format Jekyll websites
  19. Windows Tile Pin Picture to Website Feed

  20. Data Visualization using Tableau