使用开源文档工具docsify,用写博客的姿势写文档
前提
❝
下面的简介摘抄自docsify的官网 https://docsify.js.org 中的简介
❞
「docsify」是一个神奇的文档网站生成器。他可以快速帮你生成文档网站。不同于GitBook
、Hexo
的地方是它不会生成静态的.html
文件,所有转换工作都是在运行时。如果你想要开始使用他,只需要创建一个index.html
就可以开始编写文档并直接部署在GitHub Pages
(码云Pages
、阿某云OSS
或者鹅云COS
等等)。它的主要特性如下:
无需构建,写完文档直接发布(运行时
markdown
文档转换)容易使用并且轻量(压缩后 ~21kB,当然这里不包括
markdown
文档的大小)智能的全文搜索
丰富的
API
支持
Emoji
,可以在文中添加表情兼容
IE11
支持服务端渲染
SSR
「docsify」的最大优势是可以让使用者感受到「用写博客的姿势去编写文档,反过来说也行:用写文档的姿势去写博客」。docsify
的学习成本很低,部署简单,官方文档十分完善,原则上只需要理解markdown
的语法和Node.js
的安装即可,对于非IT
技术从业者也十分友好。知名的技术公众号号主「JavaGuide」的站点就是采用docsify
构建的。下文简单介绍docsify
的使用姿势。
安装docsify和初始化项目
docsify
是一个Node.js
插件,所以需要提前安装Node.js。安装完毕后,通过下面命令全局安装docsify
:
npm i docsify-cli -g
假设磁盘中有一个/docsify-demo
目录,在该目录下可以直接通过docsify init
命令初始化项目:
# 先进入docsify-sample目录,在docsify-sample目录打开命令行
docsify init
命令执行成功后,会在项目的目录生成三个新的文件如下:
index.html
为入口文件,css
、js
以及配置项都在此文件中修改。README.md
会作为默认主页内容渲染。.nojekyll
用于阻止GitHub Pages
忽略掉下划线开头的文件。
接着调用docsify serve
命令然后访问http://localhost:3000
即可进行本地预览,效果如下:
❝
下面在简单介绍docsify的功能使用的时候,全部使用默认的配置参数,其实一般情况下,不太建议进行默认配置项的修改。
❞
docsify
的配置项修改或者静态资源增添基本都在index.html
文件中操作,而其他markdown
文件(包括内建的侧边栏、封面文件和自己添加的文章)都是运行时加载和渲染的。
基本配置
一份基本的配置项如下:
<!DOCTYPE html>
<html lang="en"><head><meta charset="UTF-8"><title>神奇的docsify</title><meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" /><!-- 设置浏览器图标 --><link rel="icon" href="/favicon.ico" type="image/x-icon" /><link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" /><meta name="description" content="Description"><meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"><!-- 默认主题 --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head><body><!-- 定义加载时候的动作 --><div id="app">加载中...</div><script>window.$docsify = {// 项目名称name: 'docsify-demo',// 仓库地址,点击右上角的Github章鱼猫头像会跳转到此地址repo: 'https://github.com/zjcscut/docsify-demo',// 侧边栏支持,默认加载的是项目根目录下的_sidebar.md文件loadSidebar: true,// 导航栏支持,默认加载的是项目根目录下的_navbar.md文件loadNavbar: true,// 封面支持,默认加载的是项目根目录下的_coverpage.md文件coverpage: true,// 最大支持渲染的标题层级maxLevel: 4,// 自定义侧边栏后默认不会再生成目录,设置生成目录的最大层级,建议配置为1或者2subMaxLevel: 2}</script><script>// 搜索配置window.$docsify = {search: {maxAge: 86400000,paths: auto,placeholder: '搜索',noData: '找不到结果',depth: 4,hideOtherSidebarContent: false,namespace: 'docsify-demo',}}</script><!-- docsify的js依赖 --><script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script><!-- emoji表情支持 --><script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script><!-- 图片放大缩小支持 --><script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script><!-- 搜索功能支持 --><script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body></html>
还有更多配置项可以参考docsify
文档中的定制化 - 配置项
一小节,定制的东西越多,维护的难度就越大。侧边栏、导航栏和封面都建议采用默认的文件渲染:
组件 | 文件 |
---|---|
侧边栏 |
/_sidebar.md
|
导航栏 |
/_navbar.md
|
侧边栏 |
/_coverpage.md
|
侧边栏与导航栏
「导航栏」需要在根目录的index.html
或者_navbar.md
文件中配置,可以使用emoji
,这里修改index.html
文件如:
<!-- index.html --><body><nav><a href="https://throwx.cn">???????? Throwable's Blog</a><a href="https://spring.throwx.cn">❤️❤️ Spring专栏</a></nav><div id="app">加载中......</div>
</body>
效果如下:
「侧边栏」需要在根目录的_sidebar.md
文件中配置,基本的格式是:
* 第一个章节的标题* [第一个章节第1篇文章的标题](第一个章节第1篇文章的标题的markdown文件)* [第一个章节第2篇文章的标题](第一个章节第2篇文章的标题的markdown文件)......* 第二个章节的标题* [第二个章节第1篇文章的标题](第二个章节第1篇文章的标题的markdown文件)* [第二个章节第2篇文章的标题](第二个章节第2篇文章的标题的markdown文件)......
渲染后的侧边栏效果是:
第一个章节的标题- 第一个章节第1篇文章的标题- 第一个章节第2篇文章的标题
第二个章节的标题- 第二个章节第1篇文章的标题- 第二个章节第2篇文章的标题
主题切换
❝
切换主题只需要在根目录的index.html切换对应的主题css文件即可
❞
目前docsify
官方中列出来的所有支持主题和预览效果如下:
Vue
(默认主题):<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">
Buble
:<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">
Dark
:<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
Pure
:<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">
Dolphin
:<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">
Docsify-Themeable-Default
:<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
Docsify-Themeable-Sample
:<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">
Docsify-Themeable-Sample-Dark
:<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">
最有一款合你心水。
设计封面
封面需要在根目录的_coverpage.md
文件中配置,例如docsify
官方文档的封面内容如下:
<!-- _coverpage.md -->![logo](https://throwable-blog-1256189093.cos.ap-guangzhou.myqcloud.com/202009/_media/icon.svg)# docsify <small>3.5</small>> 一个神奇的文档网站生成器。- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#docsify)
渲染效果如下:
笔者也参照此配置做了一个丑丑的主页,内容如下:
![logo](https://throwable-blog-1256189093.cos.ap-guangzhou.myqcloud.com/202009//leaf.svg)# Spring Album <small>0.0.1</small>> 试下写个Spring相关的专栏,这是原始版本,暂定包括下面的栏目:- `SpringBoot2.x`入门系列
- `SpringBoot2.x`进阶和实战
- `SpringBoot`源码系列[GitHub](https://github.com/zjcscut/spring-boot-guide)
[Get Started](#Spring)
渲染效果如下:
封面的内容可以使用html
或者markdown
语法编写,自由度极高。
❝
封面的背景颜色是随机切换的,可以使用
![color](#f0f0f0)
设置固定的背景色❞
docsify项目部署
主要介绍GitHub Pages
和腾讯云COS
的部署,其他类似于Coding Pages
或者阿里云OSS
的部署方式等等可以参照下面介绍的两种方式进行部署。
部署在GitHub Pages
先建一个Github
仓库,把项目文件推送上去:
点右上角红圈中的Settings
按钮,配置Github Pages
:
保存完毕之后,配置一下自定义的域名解析,也就是把域名解析到项目的Github Pages
中,然后就可以通过自定义域名访问此项目。
❝
当然,Github也为每个账户提供一个免费的子域名:账号.github.io,需要建一个命名为"账号.github.io"仓库,把项目文件推上到此仓库,再配置一下Github Pages的属性即可通过"账号.github.io"访问此项目。
❞
部署在腾讯云COS
笔者已经把一个子域名spring.throwx.cn
解析到腾讯云COS
的docsify
项目中,过程很简单。先创建一个对象存储的桶设置为「公有读私有写」:
接着把整个docsify
项目中的文件拷贝到桶中,「index.html
文件必须在桶的根目录」:
然后配置桶的基本配置 - 静态网站
中的索引文档(主页)如下:
做完这一步之后,就可以通过COS
的公网域名访问docsify
项目。最后再把子域名解析到COS
的内网域名即可通过自定义的子域名访问该项目,效果如下:
❝
腾讯云新用户有六个月的COS免费试用特权,建议尝鲜。
❞
小结
如果喜欢markdown
语法,并且希望用写博客的姿势去编写文档,或者用写文档的姿势去写博客,可以尝试一下docsify
,你应该会喜欢上这个优秀的开源工具的。
参考资料:
docsify
官方文档:https://docsify.js.org
示例项目仓库:
Github
:https://github.com/zjcscut/docsify-demo
示例项目在线演示入口:
腾讯云:
https://spring.throwx.cn
推荐好文强大,10k+点赞的 SpringBoot 后台管理系统竟然出了详细教程!分享一套基于SpringBoot和Vue的企业级中后台开源项目,代码很规范!
能挣钱的,开源 SpringBoot 商城系统,功能超全,超漂亮!
使用开源文档工具docsify,用写博客的姿势写文档相关推荐
- .net编写抽奖的文档_使用开源文档工具docsify,用写博客的姿势写文档
前提 ❝ 下面的简介摘抄自docsify的官网 https://docsify.js.org 中的简介 ❞ 「docsify」是一个神奇的文档网站生成器.他可以快速帮你生成文档网站.不同于GitBoo ...
- 我从大学开始写博客,如何写一篇技术博客,谈谈我的看法!
前言 只有光头才能变强. 文本已收录至我的GitHub精选文章,欢迎Star:https://github.com/ZhongFuCheng3y/3y 我一直推崇学技术可以写技术博客去沉淀自己的知识, ...
- 程序员要写博客吗?写博客能给我们带来什么?
写博客能给我们带来什么? 首先写博客是一个需要长期坚持的事情,见过很多人写博客,能坚持下来的寥寥无几,当然坚持下来的,换来的回报和收益也是很丰厚的.你所知道的很多大佬,之所以能成长为大佬,很多都是靠长 ...
- php框架写博客,用PHP写框架用框架写应用程序
现在有一个明显的趋势让PHPer必须清醒地认识到自己无论如何被分配在两大阵营中,别无选择: 要么是开发框架,要么是开发应用程序. 乍看之下会有人骂这个说法是***子放P,本来就没有第三种,你不是就说了 ...
- 学生为什么要在CSDN写博客?
学生为什么要在CSDN写博客? 引言 写博客的好处 构建知识体系 提升写作能力 扩展人脉 为简历加分 帮助他人 为什么是CSDN 如何写博客 记录学习 总结错误 总结与展望 引言 就目前来说,学生应该 ...
- 程序员为什么值得写博客
Hire Great Writers 仿佛这是写给自己看的,不过这在其中也有着相当有趣的意义 .虽然自己算是一个能写的人,或许这算是一种不算才华的才华,写博文的意义通常不会在于去描述自己怎样,怎样.通 ...
- 优秀的程序员!=爱写博客的程序员
前几天我面试一个程序员,连续几个专业问题他都没答上来. 尴尬之余,我问他:「你没有什么理想吗?你现在最渴望的事情是什么?」 他转悠着大眼睛,不假思索道:「回去写篇博客,记录下这次面试的经验!」 真没想 ...
- 作为程序员,坚持写博客对我们有什么好处?
一 摘要 1 )写博客的担心 今天来谈谈,写博客对我的益处,说起写博客,其实我写博客的时间不长,也就10来个月时间; 之前工作的时候,看到同事每天晚上写博客,当时觉得很奇怪,就觉得写这个东西,非常浪费 ...
- 如何使用CSDN中的Markdown写博客——纯小白篇
这篇博客用来学习如何使用CSDN中的Markdown写博客 在写这篇博客前,我找了很多教程,摸索了很长时间才会用这东西写博客,现在写一个教程方便像我一样的纯小白学习如何用这个Makedown写博客. ...
- 写博客原来对程序员这么有用!手把手教你应该如何写博客
写博客的好处 面试加分 最重要 的一点放在第一位,写优质的博客可以让面试官看到你的学习过程,包括你对知识的掌握,和总结能力.现在社会上太多从培训班出来的人,很多面试管都不喜欢这一类"走捷径& ...
最新文章
- Node.js(nodejs)对本地JSON文件进行增、删、改、查操作(轻车熟路)
- vue + element +tp5 个人博客后台管理小记
- 疯狂kotlin讲义连载之运算符和表达式——区间运算符
- 怎么样MyEclipse配置Tomcat?
- TEXTMETRIC 结构详解
- linux 文件系统覆盖目录,Linux内核裁减及根文件系统定制
- git保留两个repo的commit并进行合并
- server 2008中新建AD域控制器
- 《Spring揭秘》重置版——IoC注入及绑定01
- POJ2146 Confusing Login Names [最小字符串编辑距离]
- 敏捷个人学习----为什么的力量
- 基于zookeeper实现分布式读写锁
- css居中的几种方法_css两种常用的不定宽高的水平垂直居中方法,记住它,不再为样式发愁...
- 软考资料(系统集成管理工程师)无偿分享
- JAV学习笔记—IO相关类
- 技术能力和工作能力的联系和区别
- linux下搭建DNS域名解析服务器
- springAOP切面获取入参和出参
- Pingouin: 基于pandas和numpy的统计包
- TusharePro快速入门