前言介绍
Docsify 是一个基于JavaScript的文档网站生成器,可以速轻松地搭建基于文本文档的静态网站。 它没有预设的主题,所有的网站样式都由Markdown文件生成,可以自由定制。 docsify的优点是简单易用,不需要复杂的配置,文档可以直接写在Markdown文件中,支持插件扩展和多语言支持。
准备工作
-
准备一台服务器
这里推荐雨云,雨云是国内领先的具有自主知识产权的云计算平台,有云服务器、虚拟主机、游戏云、CDN、云电脑等产品,无论你是新手小白,还是云上大佬,都能给您优秀的体验。
优惠码: yhj 👈(注册绑定微信享受5折优惠) -
本地电脑安装 npm
环境安装
全局安装 Docsify CLI
首先,推荐全局安装 docsify-cli
工具,它能极大地简化创建和本地预览文档的过程。
npm i docsify-cli -g
确保 docsify-cli
成功安装后,就可以开始初始化你的文档项目了。
初始化项目
创建文档目录
如果你想在项目的一个特定目录(例如 ./docs
)中编写文档,可以使用 init
命令来初始化这个目录。
docsify init ./docs
- index.html:作为文档入口的HTML文件。
- README.md:默认的主页内容,直接编辑此文件即可更新主页。
- .nojekyll:一个空文件,用于告知GitHub Pages不要忽略下划线开头的文件。
三、撰写文档
直接在 docs/README.md
文件中开始撰写你的文档内容。此外,你也可以在 docs
目录下添加更多 .md
文件来扩展文档页面。
四、本地预览
为了实时查看文档的渲染效果,使用 docsify serve
命令启动一个本地服务器。
docsify serve docs
默认情况下,预览页面将在 http://localhost:3000
打开,任何对文档的修改都会自动刷新页面,便于即时查看效果。
五、进阶功能
Docsify提供了一系列高级配置和特性,允许用户深度定制文档站点,提升用户体验和功能性。以下是一些关键的进阶功能及其详细说明:
1. 自定义配置
-
基础配置:在
index.html
文件的<script>
标签内,通过设置window.$docsify
对象来定制Docsify的行为。例如,你可以设置网站标题、是否启用侧边栏、指定加载的CSS或JS文件等。<script> window.$docsify = { name: '我的文档', // 网站标题 repo: '用户名/仓库名', // 显示GitHub仓库链接 loadSidebar: true, // 是否加载侧边栏,默认为false themeColor: '#3eaf7c', // 自定义主题颜色 executeScript: true, // 是否执行页面中的脚本,默认为false }; </script>
-
路由配置:可以定义更复杂的路由规则,如指定某个路径对应的具体页面。
2. 侧边栏定制
- 创建一个名为
_sidebar.md
的文件于docs
目录下,用以自定义侧边栏菜单结构。你可以使用Markdown语法来组织菜单项,包括嵌套列表来表示子菜单。
<!-- docs/_sidebar.md -->
* [首页](zh-cn/)
* [指南](zh-cn/guide)
还要配置一下配置 loadSidebar
选项
<!-- index.html -->
<script>
window.$docsify = {
loadSidebar: true
}
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
3. 插件集成
-
Docsify支持丰富的社区插件来扩展功能,例如:
- 代码高亮:通过引入 prismjs 或 highlight.js 插件来实现。
- 搜索:使用
docsify-plugin-search
插件添加全文搜索功能。 - 图表支持:集成
docsify-chart
插件展示图表。 - TOC:自动插入目录插件
docsify-toc
。
安装插件通常需要在
index.html
引入相关JS文件,并在$docsify.plugins
配置项中声明使用。
4. 主题与样式调整
-
主题切换:Docsify支持多种内置主题,通过设置
theme
属性切换,如theme: 'dark'
。 -
自定义CSS:可以通过向
$docsify
添加styles
属性来自定义样式,或者直接在页面头部链接自定义CSS文件。<link rel="stylesheet" href="path/to/my-style.css">
-
使用外部主题:许多开发者为Docsify创建了独立的主题包,你可以在GitHub等平台上寻找并按照其说明文档集成。
5. 多语言支持
- Docsify 支持多语言文档,通过配置
languages
选项,指定不同语言对应的目录路径。
6. 性能优化
- 懒加载:Docsify 默认采用懒加载模式加载Markdown文件,提升初始加载速度。
- 资源压缩:在生产环境中,确保使用像webpack这样的构建工具来压缩和优化静态资源。
六、项目部署上线
- 准备一台VPS服务器,这里拿雨云服务器来演示,服务器需要安装宝塔面板,我这里已经安装好了
- 创建一个网站,上传自己的本地项目,只需将服务器的访问根目录设定为 index.html 文件。