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

2,939 阅读4分钟

一、背景

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

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

image.png

二、技术选型

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

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

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

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

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

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

三、快速搭建

1. 开始

1.1 新建项目

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

npx create-docusaurus@latest my-website classic

1.2 启动项目

本地启动项目

yarn start

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

image.png

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',
          },
        ],
      },
    }),
};

3.3 新增文档

在 blog 路径下新建 markdown 文件,会以标题为顺序,自动生成一级目录,展示 blog 下的 markdown 文件转的静态网页。

s11364401222022 s11362001222022

在 docs 路径下新建 markdown 文件,以 markdown 文件内声明的 sidebar_position 大小排序,自动生成一级目录。展示 docs 下的 markdown 文件转的静态网页。

s11381701222022

s11383101222022

如下是文档网站效果:

Untitled7.gif

四、丰富功能

1. 自动部署

通过公司内部 talos 系统内新建项目,并在 coding 配置 webhook,实现自动部署。

中间遇到了 talos 上编译时,node 版本低于 Docusaurus 要求的 v14 问题,故只能将编译流程放在本地进行。

s11441601222022

外网可通过 Github Pages、Gitee Pages 实现自动部署。

2. 自动更新 changelog

lerna version 提供自动更新 changelog 功能,本文档系统也是为 lerna 搭建的项目服务。

规范了如下发布 lerna 版本流程,可实现更新版本时自动更新文档系统内的 changelog 页面:

  • lerna version --conventional-commits 确定版本号并自动生成 changelog;

  • npm run changelog 将自动生成的 changelog 部署至文档系统(写一个脚本复制文件至指定位置即可);

  • lerna publish from-git 发布版本。

五、总结

本文讲述了快速搭建文档系统的完整过程,总结为以下 3 点:

  • 技术选型,根据需求场景选择合适的手段实现功能;
  • 通过官方文档快速搭建网站;
  • 根据需求丰富更多功能。

希望能对你有所帮助,感谢阅读~

别忘了点个赞鼓励一下我哦,笔芯❤️

往期精彩

参考资料