Docsify
静态资源生成器，应用例子：在线开发文档。官方文档地址
1、开发
1.1、环境
需要安装 node，版本无要求。
1.2、初始化
# 全局安装 docsify 客户端
npm i docsify-cli -g
# 进入 first-doc 目录，并初始化
docsify init ./first-doc1.3、编写
需求
-
具备封面
-
顶部导航栏
-
左侧导航栏
-
搜索框
-
页面锚点
目录结构
index.html
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>开发手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="description" content="Description">
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0">
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
</head>
<body>
<!-- 顶部导航栏 -->
<nav></nav>
<div id="app"></div>
<!-- Docsify v4 -->
<script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
<script>
window.$docsify = {
// 左侧导航栏标题
name: '在线说明文档',
// 右上角跳转链接
repo: 'https://github.com',
// 启用封面
coverpage: true,
// 启用顶部导航栏
loadNavbar: true,
// 启用左侧导航栏
loadSidebar: true,
alias: {
'/.*/_sidebar.md': '/_sidebar.md',
'/.*/_navbar.md': '/_navbar.md'
},
// 子目录最大展示标题级别
subMaxLevel: 2,
// 页面定位
autoHeader: true,
search: {
maxAge: 86400000, // 过期时间，单位毫秒
paths: 'auto',
placeholder: '搜索',
noData: '没有结果!',
depth: 6, // 搜索标题的最大程度, 1 - 6
hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容
// 搜索标题的最大字符数
maximumSearchResults: 10
}
}
</script>
<!-- 搜索插件 -->
<script src="https://cdn.bootcdn.net/ajax/libs/docsify/4.13.1/plugins/search.min.js"></script>
</body>
</html>_coverpage.md
<!-- _coverpage.md -->
# docsify <small>3.5</small>
> 一个神奇的文档网站生成器。
- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题
[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](01.dev/first-dev.md)_navbar.md 和 _sidebar.md
* [开发](/01.dev/)
* [first](/01.dev/first-dev.md)
* [测试](/02.test/)
* [first](/02.test/first-test.md)
* [second](02.test/second-test.md)
* [生产](/03.prod/)
* [first](/03.prod/first-prod.md)如果链接指向的是路径，而不是 md 文件，那么会默认读取该路径下的 README.md 文件
1.4、预览
docsify serve first-doc封面
内容页
2、部署
2.1 GitHub
在 GitHub 创建仓库，然后设置 GitHub Page，并选择部署的分支和目录，设置好之后，就会基于你的账号名生成二级域名，例如：利用 GitHub Page 部署的开发手册。
2.2、Vercel
静态网页部署，支持与 GitHub 结合，实现 CICD，参考：从 0 开始基于 docsify + vercel + github 免费搭建属于自己的博客 – 掘金。
基于 vercel 部署的，不过国内屏蔽了：dev-manual
2.3、Gitee
创建 Gitee Page 并上传，不过目前 Gitee Page 已经暂停服务，也没有明确告知服务会不会恢复，Gitee Pages 暂停提供服务 什么时候可以恢复 · Issue #I9RGKI · 开源中国/Gitee Feedback – Gitee.com。
2.4、Nginx
server {
listen 3000;
server_name localhost;
# 资源绝对路径
root /opt/web/first-doc;
index index.html index.htm index.php;
}2.5、Docker
dockerfile
FROM node:latest
LABEL description="A demo Dockerfile for build Docsify."
WORKDIR /op/web/first-doc
RUN npm install -g docsify-cli@latest
EXPOSE 3000/tcp
ENTRYPOINT docsify serve .构建运行
# 构建
docker build -f Dockerfile -t docsify/demo .
# 运行
docker run -itp 3000:3000 --name=docsify -v $(pwd):/op/web/first-doc docsify/demo3、遇到问题
-
多个搜索框，指引：关于当前docsify@4版本的存在的bug – 简书
-
docsify cdn 资源获取失败，建议使用国内 CDN，获取：docsify
参考