基于Docusaurus搭建

tip

工具文章需要具有可操作性，并且自己动手实践验证过的，不要直接copy网上技术文章，方便复用。
如有不对，恳请指点。

在本文开始之前，请先确保你准备就绪：

科学上网的条件
随机应变的能力
一点儿英语基础

配置本地环境

安装 Node.js

访问 Node.js 官网，下载并安装 Node.js。

VS Code 的安装配置

我们用 VS Code 作为本地编辑器，用于修改网站框架、编写文章。

首先，到 VS Code 官网 下载安装 VS Code。

软件安装完成后，我们可以选装以下两个插件：

Chinese (Simplified) Language Pack：汉化 VS Code 界面
Markdown All in One：提供更多 Markdown 语法支持

安装插件后，可能需要按提示重启 VS Code。

更新npm 镜像源

// 查看镜像源

npm config get registry

// 设置淘宝源
npm config set registry https://registry.npmmirror.com/

安装 Docusaurus 框架

切换到需要建立网站项目的目录。

例如：我想要在电脑的 D 盘下建立一个名为 wiki 的文件夹，作为这个知识库项目。那么请在 VS Code 内选择 文件 - 打开文件夹，点击 D 盘，并点击 选择文件夹

使用 npx 创建网站：

npx create-docusaurus@latest [name] [template]

例如，如果我的网站项目文件夹的名字为 wiki，那就用 wiki 替换掉 [name]，而根据 官方文档， [template] 指的是网站模板的主题，这里我们将其替换为 classic 即可。所以此处我们执行的命令为：

npx create-docusaurus@latest wiki classic

我们在 VS Code 内使用快捷键 Ctrl + ` 打开终端，把上面的那行代码粘贴进来并敲击回车，耐心等待加载完成。

当加载完成后，我们在终端内使用命令切换到网站文件夹目录：

cd [name]

其中，[name] 替换为你网站项目文件夹的名字，例如在上一步我们使用的是 wiki。

接着，执行以下命令：

npm run start

执行网站的本地部署。等待部署进度完成后，它会自动在浏览器打开 localhost:3000 页面，如果一切顺利，你可以看到网站已经成功生成。

将网站部署至云端

上一个步骤，我们成功生成了网站，但它只是被部署在了本地，从互联网上是无法访问到这个站点的。我们需要将网站部署至云服务器，让别的用户也可以从互联网任意访问。

注册 GitHub 账户

在 GitHub 官网 注册 GitHub 账户。

安装 Git

我们从 Git 官网 下载 Git 软件，并完成安装。

重启 VS Code，召出终端，粘贴以下的命令初始化 Git：

git config --global user.name "username"
git config --global user.email "email@example.com"

此处需要把 "username" 替换为你的 Git 提交用户名，推荐与刚刚在 GitHub 注册的账户名一致，例如我将其替换为 linyuxuanlin。"email@example.com" 同理，替换为 GitHub 注册的邮箱即可。

在 VS Code 内配置项目仓库

为了接下来能推送到 GitHub 服务器上，我们需要在 VS Code 内配置项目 Git 仓库，并上传到 GitHub 上。

在 VS Code 内使用快捷键 Ctrl + Shift + G 切换到源代码管理界面，初始化项目 Git 仓库，并作出首次提交。

随后，使用快捷键 Ctrl + Alt + S 将本地 Git 仓库推送到 GitHub（按提示登录 GitHub 账户即可）。

使用 Vercel 云端部署网站

此处 Vercel 的功能，相当于 GitHub Action + GitHub Pages，即自动持续部署 + 静态网站展示。选择 Vercel 是因为其生成的静态网站，国内访问速度相比 GitHub Pages 会快很多。

首先，直接访问 Vercel 的 GitHub 登录页面 ，使用 GitHub 账户注册 Vercel 账户。

完成之后，点击网页上的 New Project，导入 GitHub 响应的仓库（例如我们之前建立的 wiki 仓库），此处可能需要根据提示，再进行一次 GitHub 的登录。导入之后，一路点击 Next 继续，很快网站就能部署成功了。

大概讲一下配置（typescript方式）

配置首页的两种方式（我们选了第二种）

1. 按官方模版配置index.js去修改，然后适配样式

2. 直接用docs作为主页设置slider为根目录

docs: {
    routeBasePath: "/",
    sidebarPath: './sidebars.js',
    // Please change this to your repo.
    // Remove this to remove the "edit this page" links.
}

配置栏目

id: home
title: Welcome To Here
sidebar_label: 欢迎加入
sidebar_position: 1 // 设置为第一个展示
slug: /

{
  "label": "高效工具",
  "position": 100, // 分类的相对位置
  "link": {
    "type": "generated-index",
    "description": "高效工具"
  }
}

配置搜索

npm install --save @docusaurus/theme-mermaid

npm install --save @easyops-cn/docusaurus-search-local

markdown: {
mermaid: true,
},

themes: [
'@docusaurus/theme-mermaid',
[
    require.resolve("@easyops-cn/docusaurus-search-local"),
    {
    indexPages: true,
    hashed: true,
    language: ["zh", "en"],
    docsRouteBasePath: "/docs",
    highlightSearchTermsOnTargetPage: true,
    explicitSearchResultPath: true,
    },
],
],

配置图床

这个在pigGo章节会单独写，这里不在赘述。

配置评论插件

选型

需要支持国内站点
开源，免费，方便集成

综合以上两点选了Valine

创建 Valine 组件: 在 src/components 目录下创建一个新的 Valine 组件文件 ValineComponent.js。

// src/components/ValineComponent.js
import React, { useEffect } from 'react';

const ValineComponent = () => {
  useEffect(() => {
    const interval = setInterval(() => {
      if (window.Valine) {
        new window.Valine({
          el: '#vcomments',
          appId: 'YOUR_LEANCLOUD_APP_ID',
          appKey: 'YOUR_LEANCLOUD_APP_KEY',
          placeholder: '在这里输入评论...',
          path: window.location.pathname,
        });
        clearInterval(interval);
      }
    }, 100);
  }, []);

  return <div id="vcomments"></div>;
};

export default ValineComponent;

创建 Valine 包装组件: 在 src/components 目录下创建一个新的 Valine 包装组件文件 ValineWrapper.js。

// src/components/ValineWrapper.js
import React from 'react';
import ValineComponent from './ValineComponent';

const ValineWrapper = () => {
  return (
    <div>
      <h2>评论区</h2>
      <ValineComponent />
    </div>
  );
};

export default ValineWrapper;

在 Markdown 文件中使用 Valine 包装组件: 在你的 Markdown 文件中引入并使用 ValineWrapper 组件。例如，在 docs/my-doc.md 文件中：

---
id: my-doc
title: My Document 
sidebar_label: commmit test
sidebar_position: 2 
---

# My Document

这是我的文档内容。

import ValineWrapper from '@site/src/components/ValineWrapper';

<ValineWrapper />

确保 Docusaurus 配置正确: 确保在 docusaurus.config.js 中正确引入 Valine 的脚本。

和plugins同级即可

module.exports = {
  // 其他配置项
  scripts: [
    {
      src: 'https://unpkg.com/valine@1.4.14/dist/Valine.min.js',
      async: true,
    },
  ],
};

请确保所有文件路径和文件名正确无误

最后使用npm start 重启应用

保证每个docs目录下的文件都有评论

// src/theme/DocItem/index.js
import React from 'react';
import DocItem from '@theme-original/DocItem';
import ValineWrapper from '@site/src/components/ValineWrapper';

export default function DocPage(props) {
    return (
        <>
            <DocItem {...props} />
            <ValineWrapper />
        </>
    );
}

总结

这篇文章我们c实现了基于 Docusaurus 的知识库的本地和云端部署。本文的过程中如果遇到问题，可以联系我微信反馈。

github.com 的响应时间过长

192.30.255.113 github.com
#备用地址1
#13.250.177.223 github.com   
#备用地址2
#52.74.223.119  github.com

#docker
192.168.0.102 host.docker.internal
192.168.0.102 gateway.docker.internal
10.0.4.106 host.docker.internal
10.0.4.106 gateway.docker.internal
192.168.1.199 host.docker.internal
192.168.1.199 gateway.docker.internal
47.99.80.122 activity.api-iot.cn

#Github
151.101.193.194 github.global.ssl.fastly.net 
13.229.188.59 github.com
192.30.255.113 github.com
199.232.28.133 raw.githubusercontent.com

参考与致谢

Docs·Docusaurus

配置本地环境​

安装 Node.js​

VS Code 的安装配置​

更新npm 镜像源​

安装 Docusaurus 框架​

将网站部署至云端​

注册 GitHub 账户​

安装 Git​

在 VS Code 内配置项目仓库​

使用 Vercel 云端部署网站​

大概讲一下配置（typescript方式）​

配置首页的两种方式（我们选了第二种）​

1. 按官方模版配置index.js去修改，然后适配样式​

2. 直接用docs作为主页设置slider为根目录​

配置栏目​

配置搜索​

配置图床​

配置评论插件​

选型​

综合以上两点选了Valine​

总结​

参考与致谢​

评论区