查看原文
其他

实战 | docsify+云开发,高效创造你的文档网站

鱼皮 程序员鱼皮 2022-08-14

技术文档是程序员必备的参考书。那么如何高效地编写简洁优雅的技术文档,并快速发布到互联网上供他人阅览呢?

你可能听说过GitBook,但毕竟是国外的网站,访问速度慢。

你可能听说过简书,但在简书写文档会受到很多限制,不够灵活便捷。

神器来了,docsify 是一个动态生成文档网站的工具。有了docsify,我们只要把时间投入到文档内容的编写中,而无需关心格式,docsify能自动帮我们生成简洁优雅的文档网站,还有多种主题哦。

生成的文档网站样式如下,非常清爽:

docsify的文档使用Markdown语法编写,如果你还不会编写Markdown,请先花十分钟学习Markdown语法教程。

想要将docsify生成的文档网站发布出去,以前我们会选择GitHub Pages来进行网站托管。但由于GitHub是国外网站,会导致你的文档网站访问速度较慢。

但现在,可以在腾讯云开发上托管你的docsify文档啦!不需要再忍受中美网络之间的波动导致的网络性能差和速度慢的问题啦!

云开发(CloudBase)是一款云端一体化的产品方案 ,采用 serverless 架构,免环境搭建等运维事务 ,支持一云多端,助力快速构建小程序、Web应用、移动应用。

云开发静态网站托管支持通过云开发SDK调用服务端资源如:云函数、云存储、云数据库等,从而将静态网站扩展为全栈网站。

无论是腾讯云·云开发用户,还是小程序·云开发用户,只要开通按量付费(有免费空间),即可享有云开发静态网站托管服务。


鱼皮作为一名全栈开发者,曾作为小程序云开发校园执行官,实践并在校园推广小程序+云开发技术。有着丰富的云开发实践经验(老王卖瓜),结合跨端框架和云开发能力开发过多个小程序。

下面,只需5分钟,利用docsify+云开发高效创造和部署你的个人文档网站吧!

系统依赖

在进行后续的内容前,请先确保你的电脑中安装了 Node.js 运行环境。如果没有安装,可以访问 nodejs.org 下载安装。

在本地初始化一个docsify文档网站

首先,我们先安装 docsify-cli 工具,可以方便创建及本地预览文档网站。
npm i docsify-cli -g
安装完成后,直接通过 init 初始化项目。
docsify init mydocs
会在当前目录下创建mydocs目录,目录结构如下:
README.md 入口文件index.html 会做为主页内容渲染.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件,不用关心
直接编辑 README.md 就能更新网站内容,当然也可以写多个页面
现在让我们修改README.md为自己想要的内容,使用vim命令(也可以自己在编辑器软件中修改)
vim mydocs/README.md

最后通过 docsify serve 命令在本地启动网站服务器,支持热加载,修改文档后自动更新,做到实时预览。
docsify serve mydocs
可以看到如下提示:

在浏览器打开 http://localhost:3000 即可查看效果:


文档网站已经生成,但此时仅自己本地可见。如何让其他人看到自己的网站呢?
我们可以利用云开发的静态托管部署功能,只需几步,轻松发布自己的网站。


用静态托管部署你的文档网站


首先进入腾讯云的
云开发(cloudbase)控制台

点击立即创建,开通一个云环境:

注意选择是按量计费的模式(只有按量计费才能开通静态网站托管),可使用免费资源,超过用量部分才计费。

点击立即开通,喝杯 ☕️,稍等片刻即可创建完成。

创建完成后,进入到提示页,点击开始使用,初始化静态网站服务。

现在我们就可以使用云开发提供的静态网站服务了,有两种使用方式:

1. 通过界面上传

初始化完成后,自动进入刚刚创建的云开发环境。在文件管理页,点击上传文件,将本机mydocs目录下的index.html与README.md两个静态文件进行上传。

进入到设置页,使用默认域名即可访问到我们的文档网站啦!

默认会读取我们上传的index.html文件进行展示,也可以自己修改索引文档。

2. 命令行上传

手动上传显得比较麻烦,我们也可以借助 cloudbase cli 以命令行的方式执行上传。首先,安装cloudbase cli:

npm install -g @cloudbase/cli
执行登录命令:
cloudbase login


在弹出的页面确认授权:

进入到云环境查看页面,复制刚刚创建的云环境id:

接着,本机打开终端,cd命令进入到mydocs目录中,执行cloudbase的deploy命令将目录中的静态网站文件给部署上去:
cd mydocscloudbase hosting:deploy . -e EnvID
这里的 EnvID 替换为刚刚复制的云环境id。

最后,和通过界面上传一样,进入到设置页,使用默认域名即可访问到我们的文档网站啦!效果如下:

One More Thing

只需简单的几步,你就可以轻松实现将创作好的文档网站部署到云开发上供大家访问了,无需再忍受 Github Pages 的龟速啦!现在还可以0元迁移哦!

不仅如此,如果你是一个自动化爱好者, 还可以试着把云开发 Cli 配置到你的 CI 环境中,实现自动部署哦~

如获取静态托管技术文档,点击下方阅读原文,进入云开发社区官网!

您可能也对以下帖子感兴趣

文章有问题?点此查看未经处理的缓存