从零开始使用Docusaurus构建文档型网站

为什么突然又来研究文档类网站了呢？

哈哈哈哈，博主也反思了自己是不是太过喜欢折腾了。文章没写几篇，网站弄了几个了。

稍作解释，博主也是基于自己想要输出的内容类型考虑的。博客类网站比较适合输出一些比较零散的内容，要篇章与篇章之间有关联，博客类网站虽然也可以做到，但是总感觉很别扭。

所以略做思索，决定后续内容进行分流，比较适合规范化、模块化、系列化学习的内容将会移到我的新网站 xixiknow docs上做，一些偏重零散化、单点技能化的放在本网站做（比如本篇文章），后续还计划做一个工具类网站（规划中…）

1. 本地安装必要环境

Docusuarus 强依赖于 Node.js 版本在 18.0 以上

首先进入 Nodejs 官网的下载地址，根据自己的系统、想要下载的版本下载安装包即可

安装过程不进行细说，一步一步安装即可，安装完成后，打开命令窗口输入node -v，能看到版本号输出即可

2. 安装 Docusaurus

找到一个心仪的空目录，打开终端，执行如下命令

npx create-docusaurus@latest my-website classic

1	npx create-docusaurus@latest my-website classic

2.1 项目结构说明

上述命令它将会创建一个包含模板文件的新目录 my-website ，该目录的目录结构如下：

|-- my-website
|   |-- README.md
|   |-- blog
|   |   |-- 2019-05-28-first-blog-post.md
|   |   |-- 2019-05-29-long-blog-post.md
|   |   |-- 2021-08-01-mdx-blog-post.mdx
|   |   |-- 2021-08-26-welcome
|   |   |-- authors.yml
|   |   `-- tags.yml
|   |-- docs
|   |   |-- intro.md
|   |   |-- tutorial-basics
|   |   `-- tutorial-extras
|   |-- docusaurus.config.js
|   |-- package-lock.json
|   |-- package.json
|   |-- sidebars.js
|   |-- src
|   |   |-- components
|   |   |-- css
|   |   `-- pages
|   `-- static
|       `-- img

|-- my-website

| |-- README.md

| |-- blog

| | |-- 2019-05-28-first-blog-post.md

| | |-- 2019-05-29-long-blog-post.md

| | |-- 2021-08-01-mdx-blog-post.mdx

| | |-- 2021-08-26-welcome

| | |-- authors.yml

| | `-- tags.yml

| |-- docs

| | |-- intro.md

| | |-- tutorial-basics

| | `-- tutorial-extras

| |-- docusaurus.config.js

| |-- package-lock.json

| |-- package.json

| |-- sidebars.js

| |-- src

| | |-- components

| | |-- css

| | `-- pages

| `-- static

| `-- img

Docusaurus 是基于 markdown 进行渲染的。通常 Docusaurus 支持文件以 .md 或 .mdx 结尾。mdx 文章可以允许嵌入 React 和 Javascript，更加的灵活。

目录中文件的详细说明

Docusaurus 可以支持两类网站内容（1）博客类（2）文档类，并为此规划了两个大目录 docs 和 blog

blog 目录是 Docusaurus 用来支持博客内容的，需要可以使用，不需要则可以通过配置禁用
- 通常 blog 目录下的文章命名会以日期开头，经过解析后则是以日期进行归档分类
- tags.yml 用来定义文章标签
docs 目录是用来存放文档类文件

Docusaurus 比较重要的配置文件：

docusaurus.config.js：项目的核心配置文件，用于配置 Docusaurus 站点的各种参数和设置。通过该文件，我们可以自定义站点的外观、功能、插件等内容
sidebars.js：定义网站文档的侧边栏，可以为不同的内容定义不同的侧边栏
static：静态资源的目录，如：网站logo

Docusaurus src目录：非文档类文件，如页面、自定义的组件

2.2 常用命令

本地运行调试

通常运行完以下命令后，将会自动在默认浏览器上打开一个链接为 http://localhost:3000/ 的页面。启动完成后，大部分修改都是即刻生效的

npm start

npm start

编译for生产

运行此命令后，将会在 my-website 目录下生成名为 build 的目录，该目录是编译后可用于生产部署的制品

npm run build

1	npm run build

3. 部署到云服务器

Docusaurus 的官方文档里列举 N 多的部署说明，具体可参见：官方部署说明，因为我的是腾讯云服务器，在官方部署说明中并没有提及，所以自行摸索了下。最终选择 Git + Github Action 做为解决方案。

3.1 创建一个 Git 仓库

该 Git 仓库的作用是用来管理前面创建的项目

1. 打开 Git 并登录，如果没有账号需要注册账号

2. 创建 Git repository，注意选择 Private 类型，保护自己的文档财富

3. 本地的项目上传 git

以下命令执行过程中，若提示没有 git 命令，需要先安装 git

cd my-website

1	cd my-website

进行 git 工程初始化

git init

git init

添加并提交所有的文件

git add .
git commit -a -m "init mywebsite"

1 2	git add . git commit -a -m "init mywebsite"

将本地的库与远程的库进行关联，以下命令可以从上面创建的库中获取

git remote add origin https://github.com/xixiknow/my-website.git
git branch -M main
git push -u origin main

git remote add origin https://github.com/xixiknow/my-website.git

git branch -M main

git push -u origin main

以上命令执行完成后，本地的工程即上传成功

3.2 自动化部署

因为我要部署到自己的腾讯服务器上，从步骤上来说，总共分为三步

将本地新增或修改的文档提交到 git 上
将项目构建成制品
将制品上传到服务器的指定目录下

除了第一步必须要手动之外，剩下的两步都手动做，事不难，但人懒。

那有没有更好的解决方式呢？有的，我们可以利用自动化能力，解决掉第2、3步。

我选择了 Github Action去完成项目构建和自动发布

懒，是促进个人进步的~

3.2.1 生成 ssh 密钥

此步骤将会生成公钥和私钥、私钥配置到 Github Action 中，公钥配置到云服务器中，配置完成后 Github Action 可以无密码登录云服务器，以便将项目制品部署到服务器上

运行以下命令，一直回车即可，公私钥文件可以在目录 ~/.ssh 下找到

公钥文件为 ~/.ssh/id_rsa.pub
私钥文件为 ~/.ssh/id_rsa

ssh-keygen

1	ssh-keygen

3.2.2 使用公钥和私钥

公钥需要配置在云服务器中，私钥需要配置到 Git 中

云服务器配置

需要将 ~/.ssh/id_rsa.pub 文件中的内容配置到 ~/.ssh/authorized_keys 中。

可以用以下命令：

cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

1	cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys

Git 配置

创建两个 Secrets，分别用于存储 SSH 私钥和公钥

SSH_PRIVATE_KEY：将 id_rsa（私钥）内容粘贴到此字段
SSH_PUBLIC_KEY：将 id_rsa.pub（公钥）内容粘贴到此字段

注意：私钥的内容必须完全复制，并且不应该泄露或与其他人共享

3.2.3 创建工作流

在以下的位置，可以创建一个工作流，该工作流的的主要目的是为了，在我们推送变更以后，会自动触发并将我们的修改发布到网站上

以下代码可以考虑粘贴直接使用，简单解释以下代码的执行步骤

监听 main 分支的变化
设置任务的运行环境
actions/checkout@v2 用于拉取到你的更改到任务的运行环境
actions/setup-node@v2 设置 nodejs 按照你指定的版本
npm install安装项目依赖
npm run build 编译项目
webfactory/ssh-agent@v0.5.3 通过将 SSH 私钥加载到 GitHub Actions 中的 SSH agent，从而允许你在后续的步骤中使用 SSH 进行连接和操作
设置密钥的权限
ssh-keyscan -H yourIP >> ~/.ssh/known_hosts 有助于避免首次连接时的安全警告
将编译后的制品发布到指定目录

name: Deploy to Server

on:
  push:
    branches:
      - main  # 监听 main 分支的推送事件

jobs:
  deploy:
    runs-on: ubuntu-latest  # 使用 GitHub Actions 提供的 Ubuntu 环境

    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Node.js
        uses: actions/setup-node@v2
        with:
          node-version: '18.x'  # 根据需要修改 Node.js 版本

      - name: Install dependencies
        run: |
          npm install

      - name: Build Docusaurus
        run: |
          npm run build

      - name: Set up SSH key
        uses: webfactory/ssh-agent@v0.5.3
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Set SSH key permissions
        run: |
          mkdir -p ~/.ssh
          echo "${{ secrets.SSH_PRIVATE_KEY }}" &gt; ~/.ssh/id_rsa
          chmod 600 ~/.ssh/id_rsa  # 设置权限为 600，确保私钥安全

      - name: Add Server to know hosts
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan -H yourIP &gt;&gt; ~/.ssh/known_hosts

      - name: Deploy to server
        run: |
          cd build
          rsync -av ./ username@yourip:yourpath # 这里配置你的用户名、主机ip，会将内容上传到云服务器上（也可以使用 git 变量的方式）
        env:
          SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}

name: Deploy to Server

on:

push:

branches:

- main # 监听 main 分支的推送事件

jobs:

deploy:

runs-on: ubuntu-latest # 使用 GitHub Actions 提供的 Ubuntu 环境

steps:

- name: Checkout code

uses: actions/checkout@v2

- name: Set up Node.js

uses: actions/setup-node@v2

with:

node-version: '18.x' # 根据需要修改 Node.js 版本

- name: Install dependencies

run: |

npm install

- name: Build Docusaurus

run: |

npm run build

- name: Set up SSH key

uses: webfactory/ssh-agent@v0.5.3

with:

ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

- name: Set SSH key permissions

run: |

mkdir -p ~/.ssh

echo "${{ secrets.SSH_PRIVATE_KEY }}" > ~/.ssh/id_rsa

chmod 600 ~/.ssh/id_rsa # 设置权限为 600，确保私钥安全

- name: Add Server to know hosts

run: |

mkdir -p ~/.ssh

ssh-keyscan -H yourIP >> ~/.ssh/known_hosts

- name: Deploy to server

run: |

cd build

rsync -av ./ username@yourip:yourpath # 这里配置你的用户名、主机ip，会将内容上传到云服务器上（也可以使用 git 变量的方式）

env:

SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}