Documenting-with-Docusaurus-V2.

Installation, Configuration and Deploy for Beginners 🚀

Autor: Danny Chávez

Table of Content

First Part.

• Objective.
• Preparation of the environment.
• Installation of Docusaurus version 2.
• Deploying the Application

Second Part.

• Structure of the Project.
• Color Palette.
• Navegation Bar and Footer.
• Creating your Documents.
• Versioning your Project.
• Blogs.

Third Part.

• From local to the world.

Fourth Part.

• Demo Online.
• Video Tutorial (English Version).
• Video Tutorial (Spanish Version).

First Part.

• Objective. 📔

This repository was created to make available a tutorial that is useful for all those people who are lovers of Information Technologies. The tutorial provides the steps to work with Docusaurus version 2. Addressing topics from the preparation of the necessary requirements to proceed with the installation. Then we will address aspects of the project description, identification of the main components. And finally we will conclude with the deployment of our work to create a github page. As an extra information, in order to achieve the goal of help you to create your own website usind docusuarus version 2, there are two video availables that were created to walkthrough with this tutorial and with this amazing open source tool by facebook. The link of the video you will find at the end of the tutorial. Also, you will be available to check our demo.

Documenting is a way of showing what is done so that other people can learn, change, create, design and share. Although it is important to mention that documenting can be a complicated task. Which can trigger a project to reach its full potential. But thanks to Docusaurus our task can be simplified. With Docusaurus you help us create and maintain websites where we can display our documentation. Thanks to the implementation of React.js, we can have support for blogs, pages with custom designs with very elegant and dynamic styles.

• Preparation of the environment. 🧰

• Verify that you have installed on your computer Node.js. To do that, we must go to our terminal and type: node -v. The previous command will give us the version that we have installed.
• Verify that you have installed on your computer Node Package Manager (NPM), Likewise, in the previous step we are going to execute the command npm -v and it will provide us with the version that we have installed. In case it is necessary to update the NPM packages, we can do it as follows: if we are working on windows we will execute the command npm install -g npm, and if we are working on MAC we can execute the command sudo npm install -g npm
• Verify that you have installed on your computer Yarn
• Verify that you have installed on your computer Gitbash(optional depending on the operating system you use) and finallly,
• Verify that you have installed on your computer a source code editor (in our case we will use Visual Studio Code)

Figure 1. Checking our environment using Gitbash.

Figure 2. Checking our environment in windows.

• Installation of Docusaurus version 2. 🔧

1. Create a directory to download Docusaurus. In our case we created a folder called project_docusauv2.
2. Enter the folder created from the preferred terminal (Gitbash, cmd, etc.)
3. Execute the npx @docusaurus/init@next init [name] "[template]" , where [name] should be replaced by any name we want and [template] by "classic" to use the page for default to be uploaded to the website. Docusaurus has the availability of using various templates such as: facebook, bootstrap and so on.

Figure 3. Downloading the dependencies for the installation.

• Deploying the Application. 📦

To run Docusaurus we use the following command from the terminal: npm run start or yarn run start and our project will be displayed in our web browser with the address http://localhost:3000.

Figure 4. Running our application in the terminal.

Figure 5. Deployment of our application in our browser through localhost.

Second Part.

• Structure of the project.📜

The /blog/ folder: contains the blog's Markdown files, which are used to display different types of content presented by different users. for • The /docs/ folder: contains the Markdown files for the documents section.
• The /src/ folder: contains source files with .js extension and style sheets (CSS). It is important to mention that any file that is within the path /src/pages will be converted within the web page. for • The /static/ folder: it is nothing more than a Static Directory. Any content within here will be copied to the root of the final build directory. Which will be used to display our website on the internet. for • The /docusaurus.config.js file: is a configuration file that contains the complete configuration of the site. for • The /package.json file: It is a React application. You can install and use any npm package you want on them. for • The /sidebar.js file: used by the documentation to specify the order of the documents in the sidebar.

• The index.js file. 🏠

The index.js file is the home page of our website. In it, the React components that are presented between the navigation bar and the footer of the page are exported. You can create your own components inside the index.js file. Since the template includes Style Sheets (CSS) created by the Docusaurus team under a structure named Infima.

Basically, all the content that we put in this file will be viewed by the users who will access our website. It is for that reason, that when deciding what type of information and images we want to show, we must have the detail and the precaution that it is relevant and serves as a presentation of our main page.

• Color Palette. 🍭

As we mentioned earlier, Infima supports Style Sheets (known as CSS) to make any color changes to our website. This action can be applied within the path src /css/custom.css. It is important to note that the color values must be added in hexadecimal (HEX) format. What does hexadecimal colors mean? Color codes are ways of representing the colors we see everyday in a format that a computer can interpret and display. Commonly used in websites and other software applications, there are a variety of formats, including Hex color codes, RGB and HSL values, and HTML color names, amongst others. The most popular are Hex color codes; three byte hexadecimal numbers (meaning they consist of six digits), with each byte, or pair of characters in the Hex code, representing the intensity of red, green and blue in the color respectively.

Color Name	HEX Color	RGB Color
White	#FFFFFF	rgb(255, 255, 255)
Silver	#C0C0C0	rgb(192, 192, 192)
Gray	#808080	rgb(128, 128, 128)
Black	#000000	rgb(0, 0, 0)
Red	#FF0000	rgb(255, 0, 0)
Maroon	#800000	rgb(128, 0, 0)
Yellow	#FFFFFF	rgb(255, 255, 0)
Olive	#C0C0C0	rgb(128, 128, 0)
Lime	#808080	rgb(0, 255, 0)
Green	#008000	rgb(0, 128, 0)
Aqua	#00FFFF	rgb(0, 255, 255)
Teal	#008080	rgb(0, 128, 128)
Blue	#0000FF	rgb(0, 0, 255)
Navy	#000080	rgb(0, 0, 128)
Fuchsia	#FF00FF	rgb(255, 0, 255)
Purple	#800080	rgb(128, 0, 128)

Table 1. List of the most Common HTML Color Codes

Figure 7. Changing colors using hex codes in custom.css file.

• Navigation bar && Footer. 🗄️

The navigation bar known as navbar allows you to add links to other pages within the same site. For this, we must provide a path, although it can also be a URL that takes us to an external link. To modify the navigation bar, we must locate ourselves within the file called docusaurus.config.js.

On the other hand, like the navigation bar, the footer component can be modified. Which is inside the docusaurus.config.js file. Links can be added that lead us to other information of interest within the site or they can be external links. Finally, we can say that we can also add text related to copyright at the bottom of the page. This can be found in the section copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, inside the file docusaurus.config.js.

Figure 8. Identification of the navigation bar and footer on the main page of our site.

• Creating your Documents. 📚

If we want to add a section so that our documents appear organized by categories, we must add a special section for them. Therefore, all of them will be presented as an organized structure, allowing easy navigation between them. If we want to add new sections we must locate ourselves within the sidebar.js file. One of the great features that Docusaurus provides is that we can provide a wide variety of documents that contain different information topics. These documents are stored within the folder named docs. To create documents we must create files that contain the extension .md. The structure that we must follow to create a document is:

---
id: part1
title: Guide to organize your trip to Disney World
---
INPUT YOUR INFORMATION IN THIS LINE

It is very important to keep in mind that every document has a unique id. By default, a document id is the name of the document (without the extension) relative to the root docs directory. For example, we will find the next structure in our project like:

website # Root directory of your site
└── docs
   ├── vacation.md
   └── guide
      └── local.md
      └── international.md

where, vacation.md id is greeting and guide/local.md id is guide/hello and lastly, guide/internacional.md id is guide/international

Why the ID´s are important? Because the ID's are what we will use to identify each document that we will use to keep our information organized. Which will be shown to users on our site in the documents section and in the sidebar.However, it is important to emphasize that IDs can also be named in a different way according to what the user put into their structure. For example, if guide/local.md's content is defined as below, its final id is guide/part1.

---
id: part1
title: Guide to organize your trip to Disney World
---
INPUT YOUR INFORMATION IN THIS LINE

There are other fields that we can add within our .md file, among which we can highlight the following:

• id: A unique document id. If this field is not present, the document's id will default to its file name (without the extension).
  
• title: The title of your document. If this field is not present, the document's title will default to its id.
  
• hide_title: Whether to hide the title at the top of the doc. By default it is false.
  
• hide_table_of_contents: Whether to hide the table of contents to the right. By default it is false.
  
• sidebar_label: The text shown in the document sidebar and in the next/previous button for this document. If this field is not present, the document's sidebar_label will default to its title.
  
• custom_edit_url: The URL for editing this document. If this field is not present, the document's edit URL will fall back to editUrl from options fields passed to docusaurus-plugin-content-docs.
  
• keywords: Keywords meta tag for the document page, for search engines.
  
• description: The description of your document, which will become the and in , used by search engines. If this field is not present, it will default to the first line of the contents.
• image: Cover or thumbnail image that will be used when displaying the link to your post.

---
id: disney
title: Membership to theme parks
hide_title: false
hide_table_of_contents: false
sidebar_label: Markdown :)
custom_edit_url: https://github.com/facebook/docusaurus/edit/master/docs/api-doc-markdown.md
description: Earn free membership for one year.
keywords:
  - disney
  - world
  - parks
image: https://i.imgur.com/mErPwqL.png
---

PRO-TIP📢:

If you don't know how to create files with the extension .md on the website called Dillinger you can create this type of file online. Best of all, once you have all your content ready, you can download it to your computer locally and then just add it inside the /docs folder of your project. That way you can create a lot of content easily and quickly.

Another way to create .md files is to copy one of the files found inside the /docs folder, place it in another path to edit it both in name and content, and then place it inside the folder /docs.

Figure 9. Creating the file called doc4 for the section of our Documents.

• Versioning your project. 🧬

Version control is important to keep our work up to date. That means that many changes or updates can happen every day. It is important to keep in mind that the updates about version control must be in correspondence with the needs of our documents or our project in general. In other words, only if it is necessary to make a change, we can carry out a series of operations so that everything that we have created in our project and documents is updated as the last version made. To carry out a version control we must locate ourselves within the package.json file and add, for example, the following script: "version": "docusaurus doc:version", then we can execute the following command npm run version <version> where "" is the new version number that will be added both for the control of our documents and their structure. That is, our sidebar

# Directory structure applying version control. Reference: https://v2.docusaurus.io/docs/versioning

website
├── sidebars.json        
├── docs                 
│   ├── foo
│   │   └── bar.md       
│   └── hello.md         
├── versions.json        
├── versioned_docs
│   ├── version-1.1.0
│   │   ├── foo
│   │   │   └── bar.md   
│   │   └── hello.md
│   └── version-1.0.0
│       ├── foo
│       │   └── bar.md   
│       └── hello.md
├── versioned_sidebars
│   ├── version-1.1.0-sidebars.json
│   └── version-1.0.0-sidebars.json
├── docusaurus.config.js
└── package.json

• Blogs.📰

If all the above seemed very interesting, there is still something else that you should know. Docusaurus allows you to create a Blog section for your content. To create a blog what you need to do is create a file with a .md extension and place it in the folder called blog. It is important to mention that the format to establish the file name must be {date}-{name}.md. For example: /blog/2020-10-05-virtual-disney-world.md

---
title: My trip to Virtual Disney World
author: Danny Chavez
author_title: Virtual Boy
author_url: https://github.com/JoelMarcey
author_image_url: https://graph.facebook.com/611217057/picture/?height=200&width=200
tags: [hello, docusaurus-v2]
description: This is my first virtual Disney World.
image: https://i.imgur.com/mErPwqL.png
hide_table_of_contents: false
---
Welcome to my first virtual trip to the theme parks of Disney World. This is a new way of making magic come to your home through the use of virtual application glasses. The experience has been unique because you can interact with your favorite characters.

<!--truncate-->

This is my first blog on Docusaurus 2.

Figure 11. Editing the parameters for our blog.

Figure 12. Viewing our blog in the browser

Third Part.

• From local to the world. 🌎

IMPORTANT NOTE⚠️ : before transferring your files locally to your Github repository you must add certain information in the docusaurus.config.js file. in the parameters related to organizationName, ** projectName **, url, baseUrl

module.exports = {
  // ...
  url: 'https://endiliey.github.io', // Your website URL
  baseUrl: '/',
  projectName: 'endiliey.github.io',
  organizationName: 'endiliey',
  // ...
};

Where:
organizationName: The GitHub user or organization that owns the repository.
projectName: The name of the GitHub repository.
url: URL of the user or organization page of your GitHub page. Generally it is: "https: //username.github.io."
baseUrl: base URL for your project. For projects hosted on GitHub pages, follow the format "/projectName/".

Figure 13. Adjustment of configuration parameters to build our file locally

Before moving your entire project to a github repository and create a github pages for many users to access from anywhere in the world, you must first build the static files on the computer where you are working. To do that you must execute the following command from the console npm run build or yarn run build. These commands create a folder with the name "build" where you have all your project. After that, you must execute the following instruction in the same terminal:

Figure 14. Creating our directory called "build"

GIT_USER=<GITHUB_USERNAME> yarn deploy Use this command without "<>"

where, "GITHUB_USERNAME" is the username that you use directly on Github. Therefore, you should replace it. In case you are using the windows console (cmd) you can execute the following instruction:

cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy

And if you are using powershell you can execute the following instruction: cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

And lastly, if you are using windows you can execute the following instruction: cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

Figure 15. Final result of passing our files locally to our repository.

• Let's do it.👨‍💻👩‍💻

Now that you know which steps you must follow in order to start using Docusaurus, it is time to create your first site in which you will document the necessary information that you consider will be available to users who visit your site.

Therefore, these are some tips that you can take into account:

1. Select a topic about which you want to share relevant information.
2. Look for images that are related to the topic.
3. Prepare the information that you are going to make available on your site.
4. Organize the information into categories.
5. Research the relevant ways to proceed with the installation. It is always a good idea to show the installation or configuration process step by step.
6. Remember to keep in mind the type of audience you will be targeting.

After all the previous aspects, I want to show you a site created as a reference in which Docusaurus was used. The topic for which it will be addressed is about Openxr. If you want to see the demo please access this LINK.

• Hurrah...! We finished the tutorial.😊😊😊😊😊

Congratulations! 🎉🎊🎉, you now know the basics of Docusaurus and have all the tools you need to create a great documentation website. We covered how to create basic documentation, manage different versions, create custom pages, customize the default website, and create blogs. Docusaurus is very flexible and customizable, which allows us to have a wide variety of integrations, search functions, tools for image optimizations, adding embedded videos, and many other things. Thanks to the advantages that Github offers us, you can create your own websites and share them with many users worldwide. If you want to see how my site looks in my repository, you can visit the following link: https://dochavez.github.io/Documenting-with-Docusaurus-V2.-/

Thank you very much for reading this tutorial and I hope it will be very useful for your future projects. Now you can start to create your own tutorial using Docusaurus.

Fourth Part.

• Video🎥🎞️🎥

Check these awesome videos created for you in order to help you with your application using Docusaurus.

Video Available in English Version
Video Available in Spanish Version

Now, check our live demo and enjoy...!!!

• License Notice. 📜

This repository and all its content is licensed by MIT. You can access to read it in this LINK