GitHub Documentation using Docusaurus

Docusaurus is an open-source tool that allows you to easily build, deploy, and maintain a website for your documentation. Here's a step-by-step tutorial on how to get started with Docusaurus

Installation

For using docusaurus , Nodejs and NPM installation is required.

Nodejs Installation

• Download Nodejs installer from https://nodejs.org/en/download/
• Execute the downloaded file
• Verify the installation by running node -v
• In case of error, add the nodejs installation folder to the PATH environment variable.
• Also, add export PATH=$PATH:"<NODEJS_FOLDER>" to the .bashrc file located in your Home folder. E.g: export PATH=$PATH:"/c/Program Files/nodejs"
• Open the bash shell and execute node -v to verify that PATH is correctly set.

Getting Started

• Execute the following command to create a docusaurus Scaffolding project.

npx create-docusaurus@latest my-website        

• The project structure created is as follows:

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock        

Project Structure Details

Project structure rundown

• /blog/ - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the path option.
• /docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the path option.
• /src/ - Non-documentation files like pages or custom React components. You don't have to strictly put your non-documentation files here, but putting them under a centralized directory makes it easier to specify in case you need to do some sort of linting/processing
• /src/pages - Any JSX/TSX/MDX file within this directory will be converted into a website page.
• /static/ - Static directory. Any contents inside here will be copied into the root of the final build directory
• /docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1
• /package.json - A Docusaurus website is a React app. You can install and use any npm packages you like in them
• /sidebars.js - Used by the documentation to specify the order of documents in the sidebar

Details on Docusaurus config:

• https://blog.logrocket.com/easy-documentation-with-docusaurus/
• https://docusaurus.io/docs/configuration

Running Server Locally

Docusaurus server can be started locally by executing following command:

npm run start        

By default server starts on http://localhost:3000/<BaseUrl>

Deployment on GitHub

• Create a Git Repository with your <ProjectName-doc>
• Create two branches with name :
• main branch gets created automatically.
• Create second branch with name gh-pages.
• main branch is where entire docusaurus relates files etc get committed.
• gh-pages branch is where the docusaurus created artifacts are checked in. <MoreDetails later>
• Add following lines to the .gitignore file to prevent superfluous checking of files not required in git:

# Dependencies
# /node_modules
/build


# Generated files
.docusaurus
.cache-loader
.docusaurus/*
# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Diagnostic reports (https://nodejs.org/api/report.html)
report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json

# Runtime data
pids
*.pid
*.seed
*.pid.lock

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage
*.lcov

# nyc test coverage
.nyc_output

# Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files)
.grunt

# Bower dependency directory (https://bower.io/)
bower_components

# node-waf configuration
.lock-wscript

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules/
jspm_packages/

# TypeScript v1 declaration files
typings/

# TypeScript cache
*.tsbuildinfo

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Microbundle cache
.rpt2_cache/
.rts2_cache_cjs/
.rts2_cache_es/
.rts2_cache_umd/

# Optional REPL history
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarn-integrity

# dotenv environment variables file
.env
.env.test

# parcel-bundler cache (https://parceljs.org/)
.cache

# Next.js build output
.next

# Nuxt.js build / generate output
.nuxt
dist

# Gatsby files
.cache/
# Comment in the public line in if your project uses Gatsby and *not* Next.js
# https://nextjs.org/blog/next-9-1#public-directory-support
# public

# vuepress build output
.vuepress/dist

# Serverless directories
.serverless/

# FuseBox cache
.fusebox/

# DynamoDB Local files
.dynamodb/

# TernJS port file
.tern-port        

• Add the following property in docusaurus.config.js file:

  deploymentBranch : 'gh-pages'        

Sample: docusaurus.config.js

title: 'My-website',
  tagline: 'All available docs for my-website',
  url: 'https://<GitHubServer>',
  baseUrl: '/my-website-docs/',

  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  favicon: 'img/Logo.png',
  organizationName: 'my-organization', // Usually your GitHub org/user name.
  projectName: 'my-website-docs', // Usually your repo name.
  deploymentBranch : 'gh-pages',        

• Deployment branch is the branch from where deployment takes place.
• Set GIT_USER variable in .bashrc file.
• Execute following command to generate deployable artifacts. The artifacts are generated in the build folder of your project.

npm run docusaurus build        

• Execute following command to validate the documentation artifacts generated are correct and as per expectation.

npm run docusaurus serve        

• The test server gets deployed locally at location : http://localhost:3000/<BaseUrl>
• Execute the following command to push and deploy the generated documentation artifacts to gitHub:
• npm run docusaurus deploy
• This commands builds the entire project, generates artifacts and pushes them to gh-pages branch of the repository.
• The server will be available at : <url>/<baseurl> property set in docusaurus.config.js. E.g:

https://myorg.github.io/my-website        

References

• Installation : https://docusaurus.io/docs/installation
• Docusaurus Configuration : https://blog.logrocket.com/easy-documentation-with-docusaurus/
• Docusaurus Configuration : https://docusaurus.io/docs/configuration
• Docusaurus Deployment : https://docusaurus.io/docs/deployment
• Markdown : https://www.markdownguide.org/cheat-sheet/
• Markdown : https://www.markdownguide.org/getting-started/
• Markdown : https://www.markdownguide.org/book/
• Visual Studio IDE - Convenient for making change to Markdown files used by docusaurus. https://code.visualstudio.com/