使用docsify 生成文档站 帮助文档生成

作为程序汪, 平时开发工作中, 难免会遇到一些对外提供系统使用文档, API 接口文档等需求.

自己开发有点傻, 不要重复造轮子, 通常我们日常遇到的需求, 基本早就有好的解决方案了.

docsify 可以即时生成您的文档网站。 与GitBook不同，它不会生成静态html文件。 相反，它可以智能地加载和解析您的Markdown 文件并将其显示为网站.

项目地址: https://docsify.js.org/

git 地址: https://github.com/docsifyjs/docsify/

MIT License

安装

npm i docsify-cli -g

初始化

docsify init ./doc.xxxx.com
# 会在当前目录下创建文件夹 doc.xxxx.com, 为了好记, 直接用了文档站点域名

运行演示

docsify serve doc.xxxx.com

# 或python 等能提供静态站点支持的程序, 请参照具体程序文档
python -m http.server 8080

添加markdown 文件

在文件夹doc.xxxx.com 下创建章节目录, 修改_sidebar.md 文件: (示例)

<!-- docs/_sidebar.md -->

* [一、系统介绍](1.系统介绍/系统介绍.md)
* [二、使用说明](2.使用说明/使用说明.md)
* 常见问题处理
	* [问题1](常见问题处理/问题1/xxxx问题处理.md)
	* [问题2](常见问题处理/问题2/xxxx问题处理.md)
	* [问题3](常见问题处理/问题3/xxxx问题处理.md)

技巧: 一般我们都使用Typora 等软件编辑markdown, 把文档中的图片设置为当前文档同级的media 文件夹下. 所以在添加markdown 文档时, 也将media 图片资源等文件夹复制过来. 如 '系统介绍.md' 文件, 同级下存放了这个文件中引用的图片media 文件夹.

部署及更新

将doc.xxxx.com 文件夹作为一个工程, 添加私有git 或者github 等, 如:

git 地址: http://git.xxxx.com/abcd/doc.xxxx.com

在服务器上安装nginx (或其他web 服务)和git 并pull 代码到nginx 配置站点目录下, 如目录为:

/opt/apps/nginx/doc.xxxx.com

当有文档更新时, 把文档提交到git, 服务器上直接从git 迁出即可.

已上, 基本半小时搞定.

感谢docsify 及其相关贡献者.