使用 docsify 快速搭建文档类型网站
发布于 2021-04-06 01:05
快速开始
全局安装 docsify-cli
npm i docsify-cli -g
初始化项目
docsify init docs
该命令会在当前目录下新建 docs 目录，并在其中初始化以下文件：
本地预览
docsify serve docs
以上命令会开始实时的预览，浏览器中输入 http://localhost:3000 就可以看到效果。试试修改目录下 README.md 的内容，修改内容将实时更新。
个性定制
docsify 提供了很方便的配置来进行个性化定制。下面2张截图展示了我们接下来的配置会达到的效果。
配置项
配置在 index.html 文件的 window.$docsify 中。多数的个性定制都是配置结合其他一同来实现的。
<script>
window.$docsify = {
repo: 'docsifyjs/docsify',
maxLevel: 3,
coverpage: true,
};
</script>
封面
在配置项中，设置 coverpage: true，开启封面渲染功能。开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。该文件的内容会被用来生成封面。
<script>
window.$docsify = {
coverpage: true,
};
</script>
# craft4j
> Java 后端开发及架构都应该知道的干货文章合集。
[GitHub](https://github.com/fatfoo/craft4j.git)
[Get Started](#craft4j)
<!-- 颜色作为自定义背景 -->
<!--  -->
<!-- 图片作为自定义背景 -->
通过 markdown 语法，我们也可以使用颜色或者图片作为自定义背景。
导航栏
在配置项中，设置 loadNavbar: true，可以自定义导航栏，配合 _navbar.md 文件进行内容的渲染。
<script>
window.$docsify = {
loadNavbar: true
}
</script>
<!-- _navbar.md -->
* [ron-point](https://github.com/fatfoo/ron-point.git)
* [精进Java](http://img.uprogrammer.cn/static/20200829154605.gif)
侧边栏
在配置项中，设置 loadSidebar: true，可以开启侧边栏。配合 _sidebar.md 文件进行内容的渲染。
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<!-- _sidebar.md -->
- SSM 实战
- [利用 Bean Validation 来简化接口请求参数校验](ssm-in-action/利用%20Bean%20Validation%20来简化接口请求参数校验.md)
- [Spring Boot 集成 JWT 实现用户登录认证](ssm-in-action/Spring%20Boot%20集成%20JWT%20实现用户登录认证.md)
- [一行代码就可以实现 Jwt 登录认证，爽呆了](ssm-in-action/一行代码就可以实现%20Jwt%20登录认证，爽呆了.md)
- 工具
- [常用 Git 命令使用教程](toolkit/常用%20Git%20命令使用教程.md)
- [入行 10 年总结，作为开发必须知道的 Maven 实用技巧](toolkit/入行%2010%20年总结，作为开发必须知道的%20Maven%20实用技巧.md)
以上会生成带目录的侧边栏。
主题
docsify 提供了多种主题，还有其他第三方贡献的主体，通过引入 css 的方式就可以方便的切换主题。如下使用了 vue 主题，想切换主题，只要放开对应 css 的注释。
<head>
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
<!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css"> -->
<!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css"> -->
<!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css"> -->
<!-- <link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css"> -->
<!-- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css"> -->
<!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css"> -->
<!-- <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css"> -->
</head>
插件
docsify 也提供了许多开箱即用的插件。以下讲讲 craft4j 中用到的 emoji 插件、搜索插件、图片缩放插件、分页导航插件。
emoji 插件
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
要正确解析 emoji 字符串，在 index.html 中引入该插件即可。
全文搜索插件
全文搜索插件会根据当前页面上的超链接获取文档内容，在 localStorage 内建立文档索引。
<!-- 配置项中对全文搜索进行配置 -->
<script>
window.$docsify = {
// 全文检索完整配置参数
search: {
maxAge: 86400000, // 过期时间，单位毫秒，默认一天
paths: [], // or 'auto'
placeholder: '搜索',
noData: '啦啦啦...你找不到我~',
// 搜索标题的最大层级, 1 - 6
depth: 4,
hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容
}
}
</script>
<!-- 引入全文搜索插件 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
图片缩放插件
<!-- 引入图片缩放插件 -->
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
分页导航插件
<!-- 引入分页导航插件 -->
<script src="//cdn.jsdelivr.net/npm/docsify-pagination/dist/docsify-pagination.min.js"></script>
代码高亮
docsify 内置的代码高亮工具是 Prism。除了 Prism 默认支持的语言外，其他添加额外的语法支持需要通过CDN添加相应的语法文件 :
<!-- java 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
<!-- bash 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<!-- properties 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-properties.min.js"></script>
<!-- yaml 代码高亮 -->
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-yaml.min.js"></script>
总结
docsify 提供了非常强大的功能来快速搭建一个高颜值的文档类型网站。只需要编写 markdown 格式的文档就可以生成网站内容。其实很适合用来管理个人或者团队的知识文档。
本文来自网络或网友投稿，如有侵犯您的权益，请发邮件至：aisoutu@outlook.com 我们将第一时间删除。
相关素材