Skip to content

Building a Personal Knowledge Base - Using Docusaurus

Continuing from the previous article, Why You Need a Knowledge Base, this article will provide a detailed guide on setting up a knowledge base using the Docusaurus framework.

Before we dive into this article, please ensure that you are prepared with:

  • Access to the internet
  • Flexibility to adapt
  • Some basic knowledge of English

Configuring Your Local Environment

Installing Node.js

Visit the Node.js official website to download and install Node.js.

Setting up VS Code

We will use VS Code as our local editor for modifying the website framework and writing articles.

First, download and install VS Code from the VS Code official website.

After installing the software, you can optionally install the following two plugins:

Once you have installed the plugins, you may need to restart VS Code as prompted.

For more detailed configuration instructions, you can refer to this article on VS Code Productivity Guide - Environment Setup.

Installing the Docusaurus Framework

Navigate to the directory where you want to create your website project.

For example, if you want to create a knowledge base project in a folder named "wiki" on your D drive, open VS Code, go to File > Open Folder, select your D drive, and choose the "wiki" folder.

Initialize your website using npx:

npx @docusaurus/init@latest init [name] [template]

For instance, if your website project folder is named "wiki," replace [name] with "wiki," and according to the official documentation, you can replace [template] with "classic" as the website template theme. Therefore, the command you would execute is:

npx @docusaurus/init@latest init wiki classic

Inside VS Code, open the terminal using the shortcut Ctrl + `, paste the command above, and press Enter. Be patient as it loads.

Once the loading is complete, switch to the website's folder directory in the terminal:

cd [name]

Replace [name] with the name of your website project folder, such as "wiki," which we used in the previous step.

Next, run the following command:

npm run start

This will deploy the website locally. After the deployment process is complete, it will automatically open the website in your browser at localhost:3000. If everything goes smoothly, you will see that the website has been successfully generated.

Deploying the Website to the Cloud

In the previous step, we successfully generated the website, but it is currently only deployed locally and inaccessible from the internet. We need to deploy the website to a cloud server so that other users can access it from anywhere on the internet.

Register a GitHub Account

Go to the GitHub official website and register for a GitHub account.

Install Git

Download Git software from the official Git website and complete the installation.

Restart VS Code, open the terminal, and paste the following commands to initialize Git:

git config --global user.name "username"
git config --global user.email "[email protected]"

Replace "username" with your Git commit username, which is recommended to be the same as the username you just registered on GitHub. For example, I replaced it with linyuxuanlin. Similarly, replace "[email protected]" with the email you used for your GitHub registration.

For more detailed configuration instructions, you can refer to this Git Learning Notes article.

Configure the Project Repository in VS Code

To be able to push to the GitHub server in the next steps, we need to configure the project's Git repository within VS Code and upload it to GitHub.

In VS Code, use the shortcut Ctrl + Shift + G to switch to the source code management interface, initialize the project's Git repository, and make the initial commit.

Then, use the shortcut Ctrl + Alt + S to push the local Git repository to GitHub (follow the prompts to log in to your GitHub account).

Deploy the Website to the Vercel Cloud

The functionality of Vercel is similar to GitHub Action + GitHub Pages, which provides automatic continuous deployment and static website hosting. We choose Vercel because the static websites generated by Vercel tend to load faster for users in China compared to GitHub Pages.

First, visit the Vercel GitHub login page, and use your GitHub account to register for a Vercel account.

After completing the registration, click on "New Project" on the website, and import the corresponding repository from GitHub (for example, the "wiki" repository we created earlier). You may need to log in to GitHub again as prompted. Once imported, simply click "Next" and the website will be deployed quickly.

Summary

In this article, we've achieved both local and cloud deployment of a knowledge base based on Docusaurus. If you encounter any issues during this process, feel free to reach out to me on WeChat for feedback. In the next article (to be updated), I will provide a detailed explanation of personalized configuration.

References and Acknowledgments

Original: https://wiki-power.com/ This post is protected by CC BY-NC-SA 4.0 agreement, should be reproduced with attribution.

This post is translated using ChatGPT, please feedback if any omissions.