如何搭建一个可维护的文档中心网站-CSDN博客

本文链接：https://blog.csdn.net/2301_79096508/article/details/149806448

一、前言

最近，不少人反馈语雀上iDms 文档出现卡顿情况，还有一些人没有使用过语雀，那么打开文档就需要登录在查看，这时候在文档不断扩大的情况下搭建一个文档站，就很有必要了。

不过网络上搭建文档中心的工具是在是太多了，利用AI，筛选出来一些工具，总结了工具的优缺点来看看选什么作为文档站搭建工具。诚然，很多路不是一下子就选定的，当然我不知道写下这些话之后，是否在后面还得返回来再次进行工具选型，但希望只需要一次就够了。

工具	优点	劣势
GitBook	云端协作，团队共享方便；自动生成美观的文档页面；支持 Markdown、API 文档等；有版本管理；有搜索、权限管理、集成支持- 免费版功能有限	私有部署已停止，需使用 SaaS 版本
HonKit	GitBook v3 的开源社区分支，支持本地部署；与 GitBook v3 插件生态兼容，自由扩展、自定义主题；生成静态站点，适合私有部署	社区维护，更新不活跃；配置复杂度较高；没有自带 Web 编辑器
Typora	一个很棒的支持 macOS、Windows、Linux 的 Markdown 编辑工具；极致流畅的 Markdown 编辑体验（所见即所得）	不具备文档站点生成功能；商业版需购买授权；没有云端存储和版本管理
Docusaurus✅	Facebook 开源，活跃社区 Markdown + React，可灵活扩展交互适合技术品牌官网 + 文档的组合站点支持多语言、版本管理、全文搜索美观的 API 文档样式，适合 SDK 文档	成果介绍：React Native · Learn once, write anywhere

简介 | Docusaurus

https://juejin.cn/post/7518188007541489704

上面👆这个文档写的还是挺好的

网站分为静态网站和动态网站，顾名思义就是那个意思；按照道理应该先确定网站类型再选择工具，但是我本人被 Docusaurus 网站给迷住了，一句 “Docusaurus 将帮助您立即构建一个 精美绝伦的文档网站” 让我入了坑，我倒要看看它的‘开箱即用的文档功能’。

二、Docusaurus 介绍

2.1 简介

⚡️ Docusaurus 将帮助您立即构建一个 精美绝伦的文档网站 。

💸 构建自定义技术栈成本高昂。与其如此，不如 专注于您的内容 ，只需编写 Markdown 文件即可。

💥 想要更多？使用 高级功能 ，例如版本控制、国际化、搜索和主题自定义。

💅 查看最佳 Docusaurus 网站以获取灵感。

🧐 Docusaurus 是一个 静态网站生成器 。它构建一个具有快速客户端导航的 单页应用程序 ，利用 React 的强大功能使您的网站具有交互性。它提供开箱即用的 文档功能 ，但也可用于创建 任何类型的网站 （个人网站、产品、博客、营销登录页面等）。

2.2 技术栈

Docusaurus 的两大技术栈是Node.js 和 React.

📌 Node.js —— 让 JavaScript 跑在服务器上
✅ 什么是 Node.js？
Node.js 是一个 JavaScript 运行时环境，让你可以在服务器端用 JavaScript 写后台程序。
以前：JavaScript 只能在浏览器里运行（前端）现在：有了 Node.js，可以用 JavaScript 写：

- 静态站点生成
- Web 服务（比如 API）
- 自动化脚本
- 工具链（比如打包器、文档生成器）

📌 React —— 前端界面的搭建框架

✅ 什么是 React？（简单来说，它帮你把网页界面拆成「组件」，每个组件是独立的，便于管理和复用。）

React 是 Facebook 开发的一个前端框架（库），用来快速构建：

- 响应式网页
- 组件化 UI
- 复杂的交互式应用

🎯 总结一句话
Node.js：管理项目、运行工具、生成网站
React：负责把网页 UI 做得好看、好用

2.3 快速入门

2.3.1 安装 Node.js

在网页上选择好环境信息，下载对应的node.js，选择LTS版本。这里我选择在macOS上部署。

由于我的电脑上有 Homebrew了，安装方法就用下面这个更快：

brew install node #从Homebrew的仓库中下载Node.js的最新稳定版本并安装。
node -v
npm -v

当我没说吧，速度挺慢的，蒜鸟蒜鸟，换个方法海阔天空。。。

不如直接下载 pkg包😭

npm -v
10.9.2
node -v
v22.17.0

npx create-docusaurus@latest my-website classic
Need to install the following packages:
create-docusaurus@3.8.1
Ok to proceed? (y) y

✔ Which language do you want to use? › JavaScript
[INFO] Creating new Docusaurus project...
[INFO] Installing dependencies with npm...

[SUCCESS] Created my-website.
[INFO] Inside that directory, you can run several commands:

  `npm start`
    Starts the development server.

  `npm run build`
    Bundles your website into static files for production.

  `npm run serve`
    Serves the built website locally.

  `npm run deploy`
    Publishes the website to GitHub pages.

We recommend that you begin by typing:

  `cd my-website`
  `npm start`

Happy building awesome websites!

npm notice
npm notice New major version of npm available! 10.9.2 -> 11.4.2
npm notice Changelog: https://github.com/npm/cli/releases/tag/v11.4.2
npm notice To update run: npm install -g npm@11.4.2
npm notice

启动网站：

cd my-website
npx docusaurus start

打开 http://localhost:3000 并按照教程操作。

2.3.2 目录结构分析

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Project structure rundown

/blog/ - Contains the blog Markdown files. You can delete the directory if you've disabled the blog plugin, or you can change its name after setting the path option. More details can be found in the blog guide
/docs/ - Contains the Markdown files for the docs. Customize the order of the docs sidebar in sidebars.js. You can delete the directory if you've disabled the docs plugin, or you can change its name after setting the path option. More details can be found in the docs guide
/src/ - Non-documentation files like pages or custom React components. 严格来说，你不一定要把非文档类文件放在这里。不过把它们放在一个集中的目录，可以让代码检查或者处理更为简便。

- /src/pages - Any JSX/TSX/MDX file within this directory will be converted into a website page. More details can be found in the pages guide

/static/ - Static directory. Any contents inside here will be copied into the root of the final build directory
/docusaurus.config.js - A config file containing the site configuration. This is the equivalent of siteConfig.js in Docusaurus v1
/package.json - A Docusaurus website is a React app. 你可以安装并使用任何 npm 包。
/sidebars.js - Used by the documentation to specify the order of documents in the sidebar

下面我们重点讲下 docs 这个部分；

2.3.3 docusaurus.config.js

docusaurus.config.js 是 Docusaurus 项目的主配置文件，它就像是整个网站的大脑，用来控制网站的行为、外观、插件等一切重要设置。

🧠 它能做什么？
类型举例说明
✅ 网站基本信息title, url, baseUrl网站名称、部署地址等
🎨 主题设置themeConfig控制导航栏、侧边栏、代码高亮、搜索等
📁 文档配置presets, docs配置文档、博客、静态资源
🧩 插件系统plugins引入额外功能，如搜索、GA、PWA 等
🌍 多语言支持i18n配置语言本地化（多语种网站）

🔍 示例讲解（精简版）
// docusaurus.config.js

module.exports = {
  title: 'IDMS 文档中心', // 网站标题
  url: 'https://idms.example.com', // 网站地址
  baseUrl: '/', // 部署路径（非根路径就写 '/docs/'）

  favicon: 'img/favicon.ico',

  organizationName: 'idms', // GitHub 项目组织名（可选）
  projectName: 'docs-site', // 项目名

  presets: [
    [
      '@docusaurus/preset-classic',
      {
        docs: {
          path: 'docs', // 文档目录
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: false,
        theme: {
          customCss: require.resolve('./src/css/custom.css'), // 自定义样式
        },
      },
    ],
  ],

  themeConfig: {
    navbar: {
      title: 'IDMS',
      logo: {
        alt: 'IDMS Logo',
        src: 'img/logo.svg',
      },
      items: [
        { to: 'docs/', label: '文档', position: 'left' },
        {
          href: 'https://github.com/idms/docs-site',
          label: 'GitHub',
          position: 'right',
        },
      ],
    },
    prism: {
      theme: require('prism-react-renderer/themes/github'),
    },
  },
};

📌 常改的配置项说明
字段作用

title浏览器标签页标题
url + baseUrl网站部署地址（重要）
themeConfig.navbar顶部导航栏配置
themeConfig.footer页脚内容
presets.docs.path文档 Markdown 文件的目录路径
sidebarPath控制侧边栏结构的配置文件路径
customCss自定义 CSS 文件位置
plugins插件数组，比如 Algolia 搜索、PWA 支持等

✅ 开发时改动这个文件需要重启吗？
一般来说：
改动 docusaurus.config.js 后，建议重启；实际上每次保存修改好的文件之后，都会自动更新；
否则有些变更不会生效（如导航栏/插件等）。

✅ 配合文件
文件用途

sidebars.js控制文档的左侧结构（目录）
src/css/custom.css添加你自己的样式
static/放置图片、下载文件等静态资源
docs/ 文档的主目录,可以创建目录来存放不同 md文档，可以利用sidebar_position来控制排放方顺序；

2.3.4 Docs文档

文档功能允许用户以层级格式组织编排 Markdown 文件。

网站的文档从低到高有四层组织架构：

独立页面。
侧边栏。
版本。
插件实例。

The guide will introduce them in that order: starting from how individual pages can be configured, to how to create a sidebar or multiple ones, to how to create and manage versions, to how to use multiple docs plugin instances.

2.3.3.1 创建文档

Doc tags

标签在前面(front matter)声明，除了文档侧栏外，还引入了另一个分类维度。

可以内联定义标签，或引用标签文件中声明的预定义标签（可选，通常为docs/tags.yml）。

下面的示例：

docusaurus引用docs/tags.yml中声明的预定义标记键
Release是一个内联标记，因为它不存在于docs/tags.yml中

---
tags:
  - Releases
  - docusaurus
---

# Title

Content

docusaurus:
  label: 'Docusaurus'
  permalink: '/docusaurus'
  description: '与 Docusaurus 框架相关的文档'

组织文件夹结构

Markdown文件在docs文件夹下的排列方式会对Docusaurus内容生成产生多种影响。然而，它们中的大多数都可以与文件结构解耦。

文档ID

每个文档都有一个唯一的id。默认情况下，文档id是相对于根文档目录的文档名称（不带扩展名）。

例如，greeting.md的ID是greeting，guide/hello.md的ID是guide/hello。

所以，不自定义就是默认；

但是，id的最后一部分可以由用户在前面定义。例如，如果guide/hello.md的内容定义如下，则其最终id为guide/part1。

---
id: part1
---

Lorem ipsum

ID用于在手写侧栏或使用与文档相关的布局组件或钩子时引用文档。

Doc URLs

默认情况下，文档的URL位置是相对于docs文件夹的文件路径，但有一些例外。也就是说，如果文件名为以下之一，则文件名将不会包含在URL中：

命名为索引（不区分大小写）：docs/Guides/index.md
命名为README（不区分大小写）：docs/Guides/README.mdx
与父文件夹同名：docs/Guides/Guides.md

在所有情况下，默认的slug只有/Guides，没有/index、/README或重复的/Guides段。

使用slug front matter 来更改文档的URL。

例如，假设网站结构如下：

website # Root directory of your site
└── docs
    └── guide
        └── hello.md

默认情况下，hello.md将在/docs/guide/hello上可用。可以将其URL位置更改为/docs/bonjour：

---
slug: /bonjour
---

Lorem ipsum

slug 将附加到doc插件的routeBasePath，默认为/docs。有关如何从URL中删除/Docs部分，请参阅仅文档模式。

如果希望文档在根目录下可用，并且具有以下路径https://docusaurus.io/docs/，你可以使用slug front matter：

---
id: my-home-doc
slug: /
---

Lorem ipsum

Sidebars

使用自动生成的侧边栏时，文件结构将决定侧边栏结构。

我们对文件系统组织的建议是：让你的文件系统镜像侧边栏结构（这样你就不需要手写你的sidebars.js文件），并使用slug front matter来定制每个文档的URL。

2.3.3.2 Sidebar 侧边栏

创建侧边栏有助于：

将多个相关文档分组
在每个文档上显示侧边栏
提供分页导航，带有下一页/上一页按钮

要在Docusaurus网站上使用侧边栏：

定义一个侧边栏文件，导出侧边栏对象字典。
将其路径直接传递给@docusaurus/plugin-docs插件，或通过@docusaurs/preset-classic传递。

export default {
  presets: [
    [
      '@docusaurus/preset-classic',
    {
      docs: {
      sidebarPath: './sidebars.js',
    },
    },
  ],
  ],
};

本节概述了文档侧边栏的各种功能。在以下章节中，我们将更系统地介绍以下概念：

Sidebar items//Autogenerated//Using multiple sidebars

Sidebar items 侧边栏项目

在上一节的示例中，我们介绍了三种类型的项目类型：文档、类别和链接，它们的用法相当直观。我们将正式介绍他们的API。还有第四种类型：自动生成，我们稍后将详细解释。

DocDoc:：链接到文档页面，将其与侧边栏相关联
链接Link：链接到任何内部或外部页面
类别Category：创建侧边栏项目的下拉列表
自动生成Autogenerated：自动生成侧边栏切片
HTMLHTML：在项目的位置呈现纯HTML
*参考*Ref：链接到文档页面，不使项目参与导航生成

自动生成侧边栏

Category item metadata

在相应的文件夹中添加一个名为“_category_.json”或“_category_.yml”的文件。你可以在其中指定任何类别元数据以及位置元数据。如果有的话，label、className、position和customProps将默认为该类别关联文档中的相应值。

position: 2.5 # float position is supported
label: 'Tutorial'
collapsible: true # make the category collapsible
collapsed: false # keep the category open by default
className: red
link:
  type: generated-index
  title: Tutorial overview
customProps:
  description: This description can be used in the swizzled DocCard

如果明确指定了链接，Docusaurus将不会应用任何默认约定。

文档链接可以相对指定，例如，如果类别是由guides目录生成的，那么"link": {"type": "doc", "id": "intro"}将被解析为ID guides/intro，只有在具有前一个ID的文档不存在时才会回退到intro。

也可以使用 `link: null` 来选择不遵循默认约定，从而不生成任何类别索引页面。

位置元数据仅在侧边栏切片中使用：Docusaurus 不会对侧边栏的其他项目进行重新排序。

Using number prefixes

有一种简单的给自动生成侧边栏排序的方法，就是给每个文档和文件夹添加一个数字前缀。这会让它们在文件系统按文件名排序时也是有序的：

docs
├── 01-Intro.md
├── 02-Tutorial Easy
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   └── 03-End.md
├── 03-Tutorial Advanced
│   ├── 01-First Part.md
│   ├── 02-Second Part.md
│   ├── 03-Third Part.md
│   └── 04-End.md
└── 04-End.md

使用多个侧边栏

你可以为每组想要分类到一起的 Markdown 文件创建一个侧边栏。

🔔Docusaurus 就是使用多侧边栏的典范之一：

考虑这个例子：

export default {
  tutorialSidebar: {
    'Category A': ['doc1', 'doc2'],
  },
  apiSidebar: ['doc3', 'doc4'],
};

当浏览文档1或文档2时，将显示教程侧边栏；当浏览文档3或文档4时，将显示API侧边栏。

后面的就得看看写网站的时候会用到哪些，再补充了～