使用docsify构建专业文档网站(上)
tags: docsify doc github
文章目录
- 1.引言
- 2.docsify简介
- 3. 使用docsify构建文档
- 3.1 构建docsify目录结构
- 3.1.1 目录结构
- 3.1.2 编写`index.html`
- 3.1.3 编写`README.MD`
- 3.1.4 修改`logding`提示
- 3.1.5 本地预览网站
- 3.1.6 使用`docsify-cli`创建
- 3.2 设置文档侧边栏
- 3.2.1 设置多文档侧边栏
- 3.2.2 设置章节目录显示
- 3.2.3 忽略页面标题在侧边栏目录显示
- 3.3 设置封面
- 3.4 编写`markdown`内容
- 3.5 选择主题样式
- 3.6 添加搜索功能
- 4. 总结
- 5.参考资料
1.引言
在软件开发过程中,编程人员经常需要写文档,如开发文档、接口文档、使用手册等,也会经常编写blog记录开发过程,技术感悟。对于这些文档,一般情况下编写人员有以下几种需求:编写简单、对外发布、格式友好、形式专业。而编写的工具则有好多,包括以下几类:
- word工具类:如office word,wps,txt等
- 平台博客类:csdn,简书,oschina等
- 自建网站类:github,hexo,gitbook,markdown等
- 知识工具类:confluence,语雀,看云等
当然,各种工具有各自的优缺点,简单一点的话,使用语雀、看云来写长系列文章或者书籍也比较适合,但作为一个开发人员,希望找一个能属于自己的,简单的,有点逼格的文档工具,特别是针对开源软件文档编写,放个pdf或者doc文档,不便于维护,格调也不够高,最好能跟github关联,即时可看,又方便维护,如此,则非docsify莫属了(当然gitboot也行)。如下可以截图看一下基于docsify构建的文档。本文针对如何使用docsify实现文档构建进行讲解,希望能帮助到想构建自己的文档网站的同学。
2.docsify简介
按docsify官网的介绍,一句话:一个神奇的文档网站生成工具
,使用它,可以使用简单的方式,构建一个专业的文档网站。如果使用过GitBook和Hexo的同学,可以知识它们使用markdown编写文档,然后转为html进行显示。而docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md
转成 .html
文件,所有转换工作都是在运行时进行。只需要创建一个 index.html
,就可以开始写文档而且直接部署在 GitHub Pages进行发布,方便、快捷、格式友好,样式不错。
3. 使用docsify构建文档
本章节将对如何使用docsify构建文档进行详细描述。
3.1 构建docsify目录结构
3.1.1 目录结构
docsify有其规范的目录结构,创建一个目录,如test
,目录下最基本的结构如下:
index.html
: 入口文件README.md
: 会做为主页内容渲染.nojekyll
: 用于阻止 GitHub Pages 会忽略掉下划线开头的文件
若在本地测试,.nojekyll
可不需要,若发布到Github Pages
,则需要此文件。
3.1.2 编写index.html
index.html
<!DOCTYPE html>
<html>
<head><meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1"><meta name="viewport" content="width=device-width,initial-scale=1"><meta charset="UTF-8"><link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body><div id="app"></div><script>window.$docsify = {//...}</script><script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
</body>
</html>
注意
此处使用在线引入docsify的js,如//unpkg.com/docsify/lib/docsify.min.js
,用户也可以直接下载此文件到本地,进行本地引用。
3.1.3 编写README.MD
文档内容均以markdown的方式编写,README.MD作为文档的首页,如下是README.MD
的内容
## 我是首页这是我的首页介绍
3.1.4 修改logding
提示
初始化时会显示 Loading...
内容,可以自定义提示信息。修改index.html
的app
的div
中的文字即可,如下:
<div id="app">加载中...</div>
3.1.5 本地预览网站
最方便的就是本地安装一个python
(不会安装的请百度),然后使用Python来启动一个服务,对于python3
,在此目录下运行以下命令即可启动:
python -m http.server 3000
3000
是开启的端口号,用户可自行定义,启动后,出现以下提示:
Serving HTTP on 0.0.0.0 port 3000 (http://0.0.0.0:3000/) ...
则表示启动成功。使用浏览器访问localhost:3000
即可访问文档。如下:
至此,已经完成最基本的文档网站了,若是把完整的文档写在README.MD
中,文档也基本完成了,可以正常显示。修改文档和index.html
后,刷新页面即可显示更新。
3.1.6 使用docsify-cli
创建
若已安装nodejs
,则可以不手动创建上面的文件,使用npm安装docsify-cli
,创建目录,然后使用docsify init ./
,它完成的工作与前面手动生成的文件是一致的。具体可参考官方文档。
3.2 设置文档侧边栏
如前面示例,默认情况下,文档侧边栏会根据当前文档的标题生成目录,且会把目录全部展开。如下所示:
但一般我们写文档或书籍,都习惯把长文档分章节编写(即每章节一个文件),然后显示时目录可折叠,更方便阅读。docsify则提供了多文档侧边栏的定制。
3.2.1 设置多文档侧边栏
假设文档结构(书结构)如下:
版权信息
序
第一篇-- 第1章-- 1.1 xxx-- 1.2 xxx-- 第2章
第二篇...
对应的文件如下(**注意:**由于docsify是根据路径作为url访问的,目录名及文件名不要使用中文或空格):
.
├── a
│ ├── 1.md
│ └── 2.md
├── b
├── copyright.md
├── index.html
├── preface.md
└── README.md
只需要两步即可完成侧边栏设置:
- (1) 在
index.html
文件中的window.$docsify
添加loadSidebar: true
,选项:
<script>window.$docsify = {loadSidebar: true}
</script>
<script src="//unpkg.com/docsify"></script>
- (2) 根目录创建
_sidebar.md
文件
编写目录内容,有链接内容则使用[xx](yy)
格式,xx
是显示内容,yy
是连接地址,连接地址以index.html
所在目录为当前目录,连接到对应文件的路径,文件后缀md
省略。有层次结构的使用空格分隔层次。如下:
* [版权信息](copyright)
* [序](preface)
* 第一篇* [第1章](a/1)* [第2章](a/2)
* 第二篇* [第3章](b/3)
设置完成后,刷新页面,显示结果如下:
3.2.2 设置章节目录显示
上述定制的侧边栏仅根据_sidebar.md
文件显示了页面大框架的链接,但各章节所在的目录(标题)没有显示,需要在index.html
文件中的window.$docsify
添加subMaxLevel
字段来设置:
<script>window.$docsify = {loadSidebar: true,subMaxLevel: 3}
</script>
<script src="//unpkg.com/docsify"></script>
设置后,效果如下:
注意:subMaxLevel类型是number(数字),表示显示的目录层级
如果md文件中的第一个标题是一级标题,那么不会显示在侧边栏,如上图所示
3.2.3 忽略页面标题在侧边栏目录显示
注意: 如果md文件的第一个标题是一级标题,那么默认已经忽略了。
当设置了 subMaxLevel 时,默认情况下每个标题都会自动添加到目录中。如果你想忽略特定的标题,可以给它添加 {docsify-ignore}
:
# Getting Started## Header {docsify-ignore}该标题不会出现在侧边栏的目录中。
要忽略特定页面上的所有标题,你可以在页面的第一个标题上使用{docsify-ignore-all}
:
# Getting Started {docsify-ignore-all}## Header该页面所有标题都不会出现在侧边栏的目录中。
3.3 设置封面
docsify默认是没有封面的,默认有个首页./README.md
。通过设置coverpage
参数,可以开启渲染封面的功能。
首先需要在index.html
文件中的window.$docsify
添加coverpage: true
选项:
<script>window.$docsify = {coverpage: true}
</script>
<script src="//unpkg.com/docsify"></script>
接着在项目根目录创建_coverpage.md
文件,内容格式如下:
![logo](_media/icon.svg)
# 我的文档网站
## 个人文档网站
> 一个神奇的文档网站生成巩固* Simple and lightweight (~12kb gzipped)
* Multiple themes
* Not build static html files[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)
[Get Started](#quick-start)
目前的背景是随机生成的渐变色,每次刷新都会显示不同的颜色。docsify封面支持自定义背景色或者背景图,在_coverpage.md
文档末尾添加:
<!-- 背景图片 -->
![](_media/bg.png)<!-- 背景色 -->
![color](#fbb30b)
注意:
1.自定义背景配置一定要在_coverpage.md
文档末尾。
2.背景图片和背景色只能有一个生效.
3.背景色一定要是#fbb30b
这种格式的。
4.icon.svg
和bg.png
需要自己创建并放到_media
目录下
设置封面后,效果如下:
3.4 编写markdown
内容
如上述示例,文本内容都是使用markdown
进行编写,关于markdown
的编写规范,可参考官方文档。markdown的编写工具有很多,熟练的可以直接使用文本进行编辑,中文的markdown工具有Typora
,cmdMarkdown
,有道云笔记
等等。
3.5 选择主题样式
docsify默认提供了不同的主题样式,默认是vue.css
。用户可以根据自己需要来使用即可。
<link rel="stylesheet" href="//unpkg.com/docsify/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">
还有一些第三方的主题样式,如:
#示例地址:
https://jhildenbiddle.github.io/docsify-themeable/#/customization
#引入方法:
link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
3.6 添加搜索功能
一般文章提供搜索功能是比较人性化的功能,在docsify中添加搜索功能,只需要在index.html
添加search
插件,然后在window.$docsify
添加search
参数即可。如下:
window.$docsify = {search: {maxAge: 86400000, // 过期时间,单位毫秒,默认一天noData: '找不到结果',//搜索不到结果时显示paths: 'auto',//自动placeholder: '搜索',//搜索框提示},}
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>
具体参数设置可参考官网
添加搜索功能后,效果如下:
4. 总结
本篇文章介绍了docsify的优点,并对使用docsify构建文档网站的步骤进行说明,分别是:引入docsify文件 -> 设置目录框架 -> 编写markdown内容 -> 设置封面/样式 -> 添加搜索功能。然后使用python启动(当然也可以使用其它web服务器如nginx,apache)提供静态网站服务即可。希望对有需要的同学有所帮助。
5.参考资料
- docsify官网: https://docsify.js.org
- docsify教程: https://segmentfault.com/a/1190000017576714
- markdown官网:http://www.markdown.cn/
使用docsify构建专业文档网站(上)相关推荐
- 使用docsify构建专业文档网站(下)
tags: docsify doc github 文章目录 1.引言 2.使用`Github Pages`部署文档 3.使用`Gitalk`添加评论功能 3.1 gitalk介绍 3.2 引入gita ...
- docsify神奇的文档网站生成工具
原文链接 个人博客-欢迎访问 docsify 是一个动态生成文档网站的工具.不同于 GitBook.Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行. 这将 ...
- Github+docsify打造在线文档网站
写在前面 搭建这个在线文档的目的是方便自己对学习笔记的查看,比较喜欢 docsify 的主题风格,所以没有用 Github Pages 直接给的主题,自己根据官方文档进行了配置,目前已经成功上线. 1 ...
- Docsify 创建文档网站
文章目录 Docsify 创建文档网站 1 引言 2 Docsify 简介 3 使用 docsify 构建文档 3.1 构建 docsify 目录结构 3.2 添加文档标题名 3.3 添加 GitHu ...
- 几分钟上线一个项目文档网站,这款开源神器实在太香了!
之前在搭建mall项目的文档网站时,使用过不少工具,比如说Docsify.VuePress.Hexo.语雀等.对比了一下,要论使用简单.上线快捷还是Docsify,几分钟上线一个网站也不是问题,今天我 ...
- 几分钟上线一个项目文档网站,这款开源神器实在太香了~
之前在搭建mall项目的文档网站时,使用过不少工具,比如说Docsify.VuePress.Hexo.语雀等.对比了一下,要论使用简单.上线快捷还是Docsify,几分钟上线一个网站也不是问题,今天我 ...
- docsify 构建文档网站之定制功能(全网最全)
作者: wugenqiang 学习笔记:https://notebook.js.org/ 微信公众号:码客 E 分享(ID:enjoytoshare) 文档后续更新地址:docsify 构建文档网站 ...
- 如何用github制作html网站,如何使用docsify和GitHub页面创建文档网站?
如何自己创建网站?文档是帮助用户使用开源项目的一个重要部分,但它并不总是开发人员的首要任务,因为他们可能更关心如何使他们的应用程序更好地使用它.这就是为什么开发人员可以更容易地发布文档.在本教程中,我 ...
- Linux在线搭建自己的文档网站
1. teedoc 简介 一款用 Python 写的文档网站生成工具,支持从 Markdown 或者 jupyter notebook 转换成 HTML,支持多文档,多语言,支持自定义页面等功能 效果 ...
最新文章
- 回发或回调参数无效。下拉菜单中使用ajax,联动菜单引起的问题解决方案
- cygwin用命令安装软件_Cygwin本地安装版
- mq幂等mysql_膜拜!看完这篇你还不懂RocketMQ算我输
- linux内核支持的加密算法,Linux Kernel(Android) 加密算法总结(三)-应用程序调用内核加密算法接口...
- python 统计excel表格_Python实现对excel文件列表值进行统计的方法
- 第五章 PYTHON标准库
- KVM: Guest CPU doesn’t match specification: missing features: hle,rtm 无法启动虚拟机,解决方法
- 为什么要从 Microsoft Store 下载 Visual Studio/VS Code?
- (干货,建议收藏)备战2021年软考中级网络工程师-01计算机硬件基础
- 微信小程序实现垂直tab标签页的切换及动态的选中下划线移动-纵向
- 【HAVENT原创】CentOS 6.5 安装nodeJS
- 园丁的乐趣 惬意的游戏,种花游戏 【安卓软件】
- 大数据分析师 VS. 大数据工程师
- 美元兑人民币汇率对黄金价格的预测
- 基于ASP.NET小微企业人力资源管理系统
- 开学啦!来淘宝教育体验开学第一课
- u盘能不能给联想服务器做系统盘,u盘能当系统盘吗?怎么把U盘做成系统盘
- 干货分享!华为模拟器Web配置防火墙
- 用示波器调出李萨如图形
- 1200000有多少个约数(只计算正约数)。
热门文章
- 智慧高速公路?重点如下
- Oracle--decode函数、(case when then else end )和(update set replace)的用法
- Jsp制作登陆界面(无后台)
- 华硕设置u盘启动linux,华硕主板怎么设置u盘启动_利用它的快捷键就可以了 - 驱动管家...
- python-实现键盘记录器
- 自然语言处理学习笔记2:分词工具及分词原理
- 主动关闭TCP连接的一方为什么要有TIME_WAIT状态
- 车企新品牌、新车型层出,数据采集分析告诉你到底哪家强
- easymock 图片_EasyMock使用总结
- origin账户申请安装使用——画图软件