Docusaurus (v2)

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.

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
   https://docusaurus.io/docs/en/installation

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
    https://codesandbox.io/s/docusaurus

    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:

    ”~/gmail_acct/Supersite”

    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:

    DOC_SITE_NAME="Supersite"
    DOC_TEMPLATE="classic"
    npx @docusaurus/init@latest init "$DOC_SITE_NAME" "$DOC_TEMPLATE"
    

21. Type “y” to answer:

    Need to install the following packages:
      @docusaurus/init@latest
    Ok to proceed? (y) y   
    

22. Navigate into generated:

    cd $DOC_SITE_NAME
    pwd
    

    For me, I’m at
    ~/gmail_acct/Supersite/Supersite

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

    or

    npx docusaurus start

    The above command opens on your default browser
    http://localhost:3000

    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:

create-a-blog-post.md 
 create-a-document.md  
 create-a-page.md      
 getting-started.md    
 markdown-features.mdx 
 thank-you.md
   

2019-05-28-hola.md        
2019-05-29-hello-world.md 
2019-05-30-welcome.md
   

src
├── css
│   └── custom.css
└── pages
    ├── index.js
    ├── markdown-page.md
    └── styles.module.css
  

docusaurus.png
 favicon.ico
 logo.svg
 undraw_docusaurus_mountain.svg
 undraw_docusaurus_react.svg
 undraw_docusaurus_tree.svg
   

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.

   https://luctst.github.io/docusaurus-starter-pack/docs/siteconfig.html

   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

   Add Content Search

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

   Add plug-ins

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

   Localization

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
    

References

https://blog.logrocket.com/easy-documentation-with-docusaurus

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