实践指南-快速搭建文档网站

站长

2022年12月11日 08:40 · 阅读数 63

一、背景

需求就是生产力，常规项目的文档说明，大多放在 README.markdown 下进行记录和说明，而对于为外部赋能的项目来说，一个对外开放的文档系统是必不可少的。

如下是可供参考一个标准的在线文档系统界面 - taro 官网：

实践指南-快速搭建文档网站

二、技术选型

首先理清搭建一个在线的文档系统的要求：

内置 markdown 文件转网页
对 SEO 友好
可通过 React 扩展网页
界面美观
文档清晰，上手简单，方便部署
拓展功能丰富，如可搜索、文档版本化

在上述需求背景下，找出了以下可供参考的技术栈：

下表格数据来源：文档网站生成工具选型

开源工具对比	Hexo	VuePress	Docute	Docsify	Docusaurus
文档生成方式	预先渲染 HTML	预先渲染 HTML	运行时解析	运行时解析	预先渲染 HTML
对 SEO 友好程度	友好	友好	不友好	不友好	友好
语法	-	Vue	Vue	Vue	React
官网地址	hexo	vuepress	docute	docsify	docusaurus
适用场景	个人博客	需要 SEO 支持的技术文档	公司或团队内部的文档系统	公司或团队内部的文档系统	需要 SEO 支持的技术文档
特点	与主题解耦，更换主题成本低	采用 vue，对 vue 开发友好	Docute（60kB）使用 Vue，Vue Router 和 Vuex	Docsify（20kB）使用的是 vanilla JavaScript	采用 React，对 React 开发友好

选择使用了上手简单、对 SEO 友好、功能丰富的 Docusaurus 来搭建文档系统。

三、快速搭建

1. 开始

1.1 新建项目

安装 Node，并创建新的 Docusaurus 站点

npx create-docusaurus@latest my-website classic

1.2 启动项目

本地启动项目

yarn start

一个本地的文档系统已经搭建完成：

实践指南-快速搭建文档网站

2. 目录结构

熟悉 Docusaurus 文档系统的目录结构，清晰后续自定义配置及文档存放位置。

.
├── blog // 包含博客的 Markdown 文件
│   └── 2022-01-13-first-blog-post.markdown
├── docs // 包含文档的 Markdown 文件
│   ├── README.markdown
│   ├── api.markdown
│   └── changelog.markdown
├── src // 非文档文件
│   ├── components
│   │   ├── HomepageFeatures.js
│   │   └── HomepageFeatures.module.css
│   ├── css
│   │   └── custom.css
│   └── pages // 转换成网站页面
│       ├── index.js
│       ├── index.module.css
│       └── markdown-page.markdown
├── static // 静态资源
│    └── img
├── docusaurus.config.js // 配置文件
└── sidebars.js // 指定侧边栏文档顺序

3. 自定义内容

熟悉了目录结构后，开始自定义配置，将初始化的文档项目，改成我们自己的内容。

3.1 配置站点元数据

包括：

title：标题
url：文档系统域名
baseUrl：域名下的一级地址
favicon：网站图标

修改 docusaurus.config.js：

const config = {
  title: 'distribute-sdk',
  url: 'http://tls-pre.jd.com',
  baseUrl: '/distribute-sdk-docs/',
  favicon: 'img/favicon.ico',
};

3.2 配置导航栏

包括导航栏、logo、主站名称、coding 地址。

修改 docusaurus.config.js：

const config = {
  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      navbar: {
        title: 'Distribute SDK',
        logo: {
          alt: 'Distribute SDK Logo',
          src: 'https://img11.360buyimg.com/ling/jfs/t1/103667/23/20676/2779/61d59cd2Ef2665258/239330f23ecbae81.png',
          href: 'docs/',
        },
        items: [
          {
            type: 'doc',
            docId: 'README',
            position: 'left',
            label: '文档',
          },
          { to: '/blog', label: 'Blog', position: 'left' },
          {
            href: 'xx', // git remote 地址
            label: 'Coding',
            position: 'right',
          },
        ],
      },
    }),
};