有了docsify神器,从此爱上看文档
有了docsify神器,从此爱上看文档
简介
一个神奇的文档网站生成工具
我们在做完项目的时候经常会写一些项目手册,来记录我们在项目开发过程中的一些开发流程、使用方式以及注意事项,分享给将会使用到这个项目的人,方便大家快速上手,让程序顺利运行。
目前比较好的方式就是写成Markdown格式的技术文档,方便我们发布在github上,同时也可以发布到博客分享平台。除此之外我们还可以借助docsify这个工具,来帮助我们快速的搭建一个小型的文档网站,它可以自动将我们写在Markdown中的标题生成目录,整个页面的配色和布局也十分舒适易读,让整个阅读体验提升了好几个level,有了docsify这个神器,再也不害怕看长长的技术文档了。
docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会将 .md
转成 .html
文件,所有转换工作都是在运行时进行。这将非常实用,如果只是需要快速的搭建一个小型的文档网站,或者不想因为生成的一堆 .html
文件“污染” commit 记录,只需要创建一个 index.html
就可以开始写文档而且直接部署在GitHub Pages。
先看一些使用docsify生成的技术文档:
Markdown Preview Enhanced
操作系统
Awesome Mac
它的docsify中文官方文档就是利用docsify生成的,展示效果一目了然。
这是我用docsify生成的豆瓣影音项目文档:https://hanxueqing.github.io/Douban-Movie/
特性
- 无需构建,写完文档直接发布
- 容易使用并且轻量 (~19kB gzipped)
- 智能的全文搜索
- 提供多套主题
- 丰富的 API
- 支持 Emoji
- 兼容 IE10+
- 支持 SSR (example)
快速安装
1. 全局安装docsify
npm i docsify-cli -g
安装成功后显示
image
2. 初始化项目
docsify init ./docs
初始化成功后,可以看到 ./docs
目录下创建的几个文件
index.html
入口文件
README.md
会做为主页内容渲染
.nojekyll
用于阻止 GitHub Pages 会忽略掉下划线开头的文件
直接编辑 docs/README.md
就能更新网站内容,当然也可以写多个页面。
image
3. 本地预览网站
运行一个本地服务器,通过 docsify serve
可以方便的预览效果,而且提供 LiveReload 功能,可以实时的预览。默认通过 http://localhost:3000访问。
docsify serve docs
image
常用配置项
Github Corner
通过设置index.html中window.$docsify的 repo
参数配置仓库地址或者 username/repo
的字符串,会在页面右上角渲染一个 GitHub Corner 挂件,点击即可跳转到Github中对应的项目地址。
<script>window.$docsify = {name: '豆瓣影音',repo: 'https://github.com/Hanxueqing/Douban-Movie.git',coverpage: true}</script>
image
封面
通过设置index.html中window.$docsify的 coverpage
参数,即可开启渲染封面的功能。
<script>window.$docsify = {name: '豆瓣影音',repo: '',coverpage: true}</script>
封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 _coverpage.md
文件,在文档中编写需要展示在封面的内容。
![logo](https://docsify.js.org/_media/icon.svg)# 豆瓣影音> 使用Vue全家桶+Node.js搭建的小型全栈项目.* 前端框架:vue-cli、vue-router、axios、vuex
* UI类库:Mint-UI、Vant
* 后端数据接口:Express、MongoDB[GitHub](https://github.com/Hanxueqing/Douban-Movie.git)
[Get Started](#quick-start)
展示效果如图:
image
目前的背景是随机生成的渐变色,我们自定义背景色或者背景图。可以参考官网文档封面这一章节自行设置。
主题
直接打开 index.html 修改替换 css 地址即可切换主题,官方目前提供五套主题可供选择,模仿 Vue 和 buble 官网订制的主题样式。还有 @liril-net 贡献的黑色风格的主题。
<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">
其他主题docsify-themeable又提供了三种样式可供选择:
docsify-themeable是一个用于docsify的,简单到令人愉悦的主题系统.
Defaults
<!-- Theme: Defaults -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
image
Simple
<!-- Theme: Defaults -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
image
Simple Dark
<!-- Theme: Simple Dark -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
image
另外还有一种在网上看到的样式:
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
多页面
目前我创建的文档是单页面的,上下滚动即可浏览全部内容。如果想创建多个页面,即点击左侧侧边栏导航跳转到不同url,就需要配置多级路由,这一功能在docsify中也很容易实现,我们需要在index.html文件中的window.$docsify
中开启loadSidebar选项:
<script>window.$docsify = {loadSidebar: true}
</script>
<script src="//unpkg.com/docsify"></script>
然后在根目录创建自己的_sidebar.md文件,配置我们需要显示的页面。详细操作步骤参考官方多页文档教程。
注:配置了loadSidebar
后就不会生成默认的侧边栏了。
插件
官方还提供了非常多实用的插件,比如说全文搜索、解析emoji表情、一键复制代码等等,完整版请参考官方插件列表。
Github Pages
和 GitBook 生成的文档一样,我们可以直接把文档网站部署到 GitHub Pages 或者 VPS 上。
GitHub Pages 支持从三个地方读取文件
docs/
目录- master 分支
- gh-pages 分支
我们推荐直接将文档放在 docs/
目录下,找到仓库的Settings设置页面
image
开启 GitHub Pages 功能并选择 master branch /docs folder
选项。
image
发布成功后会显示网站地址,通过这个地址即可在线访问你编写的技术文档了。
有了docsify神器,从此爱上看文档相关推荐
- 先自己看文档和百度再沟通
工作中遇到新的需求和技术,首先自己看文档和百度,能自己弄出来的不要去问别人. 自己无法理解,百度搜不到再去和别人沟通,不要总是问别人,自己独立解决问题.
- Jeecg社区wiki在开放,终于可以在线看文档啦!!!
Jeecg社区wiki在开放,终于可以在线看文档啦!!! 2014-12-18 scott JEECG jeecg开源社区wiki正式启动了,方便大家看文档 访问地址是: http://osbaba. ...
- 超简单的vue3.0,必看文档
1.vue概述 vue作者尤雨溪 尤雨溪毕业于上海复旦附中,在美国完成大学学业,本科毕业于Colgate University,后在Parsons设计学院获得Design & Technolo ...
- 如何用github制作html网站,如何使用docsify和GitHub页面创建文档网站?
如何自己创建网站?文档是帮助用户使用开源项目的一个重要部分,但它并不总是开发人员的首要任务,因为他们可能更关心如何使他们的应用程序更好地使用它.这就是为什么开发人员可以更容易地发布文档.在本教程中,我 ...
- 看文档学redis以及面试题2(配套发出有docker以及linux两个不同的皆可学习)
看文档学redis以及面试题(配套发出有docker以及linux两个不同的皆可学习) 遇到的坑都会讲到 这是配套的第二章内容 今天讲的是redis的五大数据类型的使用场景以及五大数据类型的常用命令以 ...
- 1015葛芮杉李睿莹|1-圖像处理与人脸识别的结合应用。群里贴图2-每组学会一个新的ffmpeg的命令,用于视音频处理(自学:看文档,搜索等)3-每组学会2个图像处理的函数,贴图
#人脸识别+裁切+粘贴 import cv2 import numpy as np import pandas as pd import os from matplotlib import pyplo ...
- 用平静的心去看文档读代码!
我发现了很严重的问题,如果心不静下来,你对文档和代码的理解能力将会大打折扣.我就是那种心都静不下来的那种,以前看mui框架和weui框架觉得他们的jquery怎么这么晦涩难懂,说的是人话么.这就是我心 ...
- docsify写一个自己的文档网站
1. docsify介绍 docsify 是一个动态生成文档网站的工具.支持 markdown 语法能直接部署在 GitHub Pages. 可以用来当做项目的说明文档,也还可以当做自己专属的知识小仓 ...
- 教你实践ASP.NET Core Authorization(免看文档教程)
准备 创建一个名为AuthorizationForoNetCore的(web)解决方案,选择Empty模板 添加相关nuget包引用Microsoft.AspNetCore.Mvc(选择最新版本) 编 ...
最新文章
- Intellij idea 14 创建简单的Web项目
- 五分钟学会使用 go modules(含在家办公使用技巧)
- MySQL-常用引擎
- Tips--创建jupyter notebook的虚拟环境
- c语言用户管理系统的知识,C语言系统用户管理系统
- Windows command
- Smali语法汇总(二)
- mysql查询月份1到31_mysql查询今天、昨天、7天、近30天、本月、上一月 数据
- li指令 汇编_51单片机(九)汇编指令
- FILCO连接WIN10出现PIN问题
- springboot + rabbitmq 做智能家居,我也没想到会这么简单
- Linux命令手册-查看文件大小常用命令(df、du、stat)(详解)
- 获取新榜微信公众号指数信息,并服务器上部署
- 高通QCC3006蓝牙5.0音频芯片简介
- 桁架工业机器人编程_工业机器人应用与编程
- 类似AV终结者的病毒分析
- matlab数据采集工具箱,MATIAB数据采集工具箱
- 将视频格式转换为gif图片格式
- 为何游戏公司青睐工作室制度?
- C 指针 | 从底层原理到花式技巧(图文详解)