第一课：安装配置

步骤一：安装 Node.js

安装 Node.js 这里不详细展开，请见：——————

验证 Node.js 是否安装成功

node -v   #应该输出版本号
npm -v     #应该输出版本号

步骤二：创建项目

先 创建并进入 项目文件夹，比如

cd D:\Notes

运行创建命令, 等待下载和初始化（可能需要几分钟

npx create-docusaurus@latest my-docs classic

my-docs 是项目名称，你可以改成自己喜欢的名称

classic 是模板，适合一般技术文档

可以看到出现了 my-docs 文件夹，进入

cd my-docs

安装依赖

npm install

运行开发服务器

npm run start

此时应该可以看到输出 Local: http://localhost:3000/

说明 Docusaurus 已成功运行，打开浏览器访问 http://localhost:3000/ 就可以看到你的技术文档站点了！

步骤三：基本介绍

到现在我们已经安装好了 Docusaurus

进入 my-docs 目录，你会看到以下结构：

my-docs/
│── docs/          # 存放 Markdown 文档
│── blog/          # 存放博客（如果不需要可以删除）
│── src/           # 站点的前端代码
│── static/        # 存放静态资源（图片等）
│── docusaurus.config.js  # 主要配置文件
│── sidebar.js     # 侧边栏配置

修改运行端口：

docusaurus 默认运行在 3000端口，并不提供外网访问

打开 my-docs/package.json，找到

"scripts": {
  "start": "docusaurus start"
}

修改为：

"scripts": {
  "start": "docusaurus start --host 0.0.0.0 --port 8080"
}

保存后直接运行

npm start

步骤四：发布文章

在 Docusaurus 中，主要有三种类型的文章：doc，page，和 blog

他们三者的区别如下：

功能	Page（页面）	Doc（文档）	Blog（博客）
适用场景	独立页面（关于我们、FAQ）更灵活的布局，而不是严格的文档结构	结构化知识（API、教程）	时间序列内容（开发日志、更新日志）
存放位置	my-docs/src/pages/	my-docs/docs/	my-docs/blog/
侧边栏支持	❌ 无	✅ 自动生成	❌ 无
适合 SEO	🚀 高	✅ 高	✅ 高
时间排序	❌ 无	❌ 无	✅ 按时间排序
支持 Markdown	✅ 是	✅ 是	✅ 是
支持 React 组件	✅ 是	❌ 否	❌ 否

我们主要使用的 是 doc，他们都存放在 docs/ 目录，可以在里面添加 Markdown 文件。

例如，创建 docs/java.md：

---
id: java
title: Java 入门
---

# Java 入门
这是一个 Java 教程文档。

但是这是不会马上显示在网站上的，后续会讲到怎么配置

我们先在 docs 文档下 重新创建文件夹，（每个文件夹保管一套知识体系）

后面我们会设置 每一个导航栏按钮 链接到 一个对应的文件夹, 文档结构如下：

D:\Notes\my-docs\docs
├─AI
│  └─Pytorch教程
├─APP
├─DataBase
├─DataScience
├─Language
├─OS
├─Others
├─WebCoding
│  ├─Docusaurus教程
│  │  ├─tutorial-basics
│  │  └─tutorial-extras
│  │      └─img
│  └─Hexo
└─WebSafety

然后在每个文件夹下创建一个 intro.md 文件，随便写一点东西进去，intro.md 一会儿会 被作为这个文件夹的目录

然后来到 sidebars.js， 如下修改

const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

  Language: [{ type: 'autogenerated', dirName: 'Language' }],
  OS: [{ type: 'autogenerated', dirName: 'OS' }],
  AI: [{ type: 'autogenerated', dirName: 'AI' }],
  DataScience: [{ type: 'autogenerated', dirName: 'DataScience' }],
  DataBase: [{ type: 'autogenerated', dirName: 'DataBase' }],
  Safety: [{ type: 'autogenerated', dirName: 'Safety' }],
  Web:[{ type: 'autogenerated', dirName: 'Web' }],
  APP: [{ type: 'autogenerated', dirName: 'APP' }],
  Others: [{ type: 'autogenerated', dirName: 'Others' }],

对应的，来到 docusaurus.config.js，找到下面这段并 如下修改

      navbar: {
        title: "Heihe's Technical Blog",
        logo: {
          alt: 'My Site Logo',
          src: 'img/mylogo.svg',
        },
        items: [
          // {
          //   type: 'docSidebar',
          //   sidebarId: 'tutorialSidebar',
          //   position: 'left',
          //   label: '所有文件',
          // },
          { to: '/docs/Language/intro', label: 'Language', position: 'left' },
          { to: '/docs/OS/intro', label: 'OS', position: 'left' },
          { to: '/docs/AI/intro', label: 'AI', position: 'left' },
          { to: '/docs/DataScience/intro', label: 'DataScience', position: 'left' },
          { to: '/docs/DataBase/intro', label: 'DataBase', position: 'left' },
          { to: '/docs/Safety/intro', label: 'Safety', position: 'left' },
          { to: '/docs/Web/intro', label: 'Web', position: 'left' },
          { to: '/docs/APP/intro', label: 'APP', position: 'left' },
          { to: '/docs/Others/intro', label: 'Others', position: 'left' },


          // {to: '/blog', label: 'Blog', position: 'left'},
          {
            href: 'https://github.com/Blackriver-T09',
            label: 'GitHub',
            position: 'right',
          },
        ],
      },

现在我们的导航栏就变成了这样：

然后点击其中一个标签，就可以跳转到 对应目录下的 intro.md 文件

Take care

在删除文件时，会出现报错的情况

这是 因为 Docusaurus 的 sidebar 自动生成机制

换句话说，当你删除 某个文件 后，Docusaurus 仍然试图在其目录中找到它，但找不到，就会报错。

默认情况下，Docusaurus 在找不到文档时会报错。你可以让它 不报错，只给出警告

因此需要修改 docusaurus.config.js

module.exports = {
  onBrokenLinks: 'warn', // 从 'throw' 改为 'warn'
  onBrokenMarkdownLinks: 'warn', // 让找不到的 Markdown 链接变成警告而不是错误
};

然后手动清理 .docusaurus 目录并重新启动

rmdir /s /q .docusaurus
npm start

My tip

docusaurus 加载不及时，因此如果出现文件、图片、文件夹没有加载出来的情况，修改一下文件内容再刷新一下就好了

My tip

文档文件和 URL 是一一映射的，比如文件地址为：\my-docs\docs\Language\intro.md

那么对应的 URL 为：notes.heihet09.com/docs/Language/intro

步骤五：编写启动文件

写一个启动文件，自动定位到项目文件夹，清理缓存，然后启动

创建 start_docusaurus.bat

@echo off
cd /d D:\Notes\my-docs
echo 清理 Docusaurus 缓存...
if exist .docusaurus ( rd /s /q .docusaurus )
echo 启动 Docusaurus...
npm start
pause

双击 start_docusaurus.bat 运行

My tip

docusaurus 基于 React，因此有时即使重启了服务器，但是旧网页上还是没有同步更新，这是浏览器的缓存导致的。只需要重启浏览器即可看到更新的 内容和结构