手把手搭建自己的文档系统 - 详细配置和部署步骤

背景介绍

近期正好有个项目需要搭建一个文档, 方便后续查询和使用, 这边调研了市面上一些常见的markdown文档系统如下:

名称	底层框架	适合常见
Docusaurus	NodeJS语言, 基于React构建，支持Markdown中嵌入React组件，适合构建大型文档网站	复杂的文档网站、博客、产品文档
MkDocs	Python语言 轻量级、易于上手，视觉效果出色，基于Markdown语法，通过YAML配置文件控制	项目文档、内部手册、个人博客或知识库
GitBook	NodeJS语言 强大的文档编写和发布工具，支持Markdown和AsciiDoc	电子书、技术文档、在线手册
Hexo	NodeJS语言 高性能、快速生成静态网站的博客框架，支持Markdown	个人博客、技术文档、小型网站
Hugo	GO语言 静态网站生成器，支持Markdown等多种标记语言	博客、文档网站、个人网站

综合看了上述不同的框架, 整体facebook的Docusaurus是一个比较好的选择, 首先采用NodeJS引擎, 以及React作为UI框架, 比较适合快速搭建文档.

环境搭建和自定义

下面介绍如何快速搭建一个Docusaurus文档系统:

1. 安装Docusaurus

首先，确保已经安装了Node.js（版本18或更高）和npm（或Yarn）。然后，通过以下命令安装Docusaurus脚手架工具：

npx create-docusaurus@latest my-website classic

上述命令将在当前目录下创建一个名为my-website的新项目，并配置好经典主题。

2. 启动开发服务器

进入项目目录并启动开发服务器：

cd my-website  
npm run start

默认情况下，浏览器将打开http://localhost:3000地址，预览网站。

3. 添加文档

在docs目录下添加Markdown文件，例如my-first-doc.md

---  
id: my-first-doc  
title: 我的第一篇文档  
---  

# 这是标题

## 这是内容

保存后，刷新页面即可看到新添加的文档。

4. 自定义网站

Docusaurus提供了丰富的自定义选项，可以通过修改配置文件和React组件来定制网站。

修改配置文件

docusaurus.config.js是Docusaurus的核心配置文件，可以在这里修改网站的标题、标签行、URL等。

const config = {  
  title: 'My Docusaurus Site',  
  tagline: 'A custom Docusaurus site',  
  url: 'https://your-docusaurus-site.com',  
  // 其他配置...  
};

自定义导航栏和页脚

在docusaurus.config.js中，可以自定义导航栏和页脚的链接和图标。

navbar: {  
  title: 'My Site',  
  logo: {  
    alt: 'My Logo',  
    src: 'img/logo.png',  
  },  
  items: [  
    {to: '/docs/', label: 'Docs', position: 'left'},  
    {to: '/blog', label: 'Blog', position: 'left'},  
    // 其他链接...  
  ],  
},  
footer: {  
  style: 'dark', // 可选值: 'light', 'dark'  
  links: [  
    {  
      title: 'Docs',  
      items: [  
        {label: 'Tutorial', to: '/docs/tutorial'},  
        // 其他文档链接...  
      ],  
    },  
    // 其他链接组...  
  ],  
  // 其他配置...  
},

创建自定义页面

在src/pages目录下创建新的React组件文件（如custom-page.js），并在其中编写页面内容。

import React from 'react';  
import Layout from '@theme/Layout';  
  
function CustomPage() {  
  return (  
    <Layout title="Custom Page">  
      <h1>This is a custom page</h1>  
      <p>You can add any content here.</p>  
    </Layout>  
  );  
}
export default CustomPage;

然后，在sidebars.js中添加指向新页面的链接，使其出现在侧边栏中。

5. 部署网站

最后，将网站部署到GitHub Pages或其他静态网站托管服务上。执行以下命令来构建并部署网站：

npm run build  
cd ..  
git init  
git remote add origin https://github.com/your-username/your-username.github.io.git  
git add .  
git commit -m "Initial commit"  
git push -u origin master

这样就可以通过github page访问网站了。

以上便是关于文档搭建的介绍, 欢迎点赞关注收藏~