Wilson Mar bio photo

Wilson Mar

Hello!

Email me Calendar Skype call

LinkedIn Twitter Gitter Instagram Youtube

Github Stackoverflow Pinterest

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

US (English)   Español (Spanish)   Français (French)   Deutsch (German)   Italiano   Português   Cyrillic Russian   中文 (简体) Chinese (Simplified)   日本語 Japanese   한국어 Korean

Overview

This is a hands-on deep-dive introduction to installing and using Docusaurus as a static (JAM stack) website builder.

  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.

    264 watching 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:

    docusaurus-mysite-483-391

    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:

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

    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

  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. Design Systems
  2. Text Editors
  3. Markdown text for GitHub from HTML
  4. 508 Accessibility

  5. HTTP/2 Transition Project Plan

  6. Docusaurus static website generator
  7. Static websites
  8. JAM Stack Website Project Plan
  9. Jekyll Site Development
  10. Gatsby app generator

  11. Website styles
  12. Website Styling
  13. VueJs front-end framework

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

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

  18. Data Visualization using Tableau