前提以下介绍节选自docsify.js.org,官网,docsify的介绍Docsify是一个神奇的文档网站生成器。他可以快速帮你生成一个文档网站。不同于Git
前提
以下介绍节选自docsify.js.org,官网,docsify的介绍
Docsify是一个神奇的文档网站生成器。他可以快速帮你生成一个文档网站。不同于GitBook和Hexo,它不会产生静电。html文件,所有的转换工作都在运行时完成。如果想开始使用,只需要创建一个index.html开始写文档,直接部署在GitHub页面(CodeCloud Pages,阿茂云OSS或者鹅云COS等)上即可。).其主要特点如下:
无需构建,写完文档直接发布(运行时markdown文档转换)容易使用并且轻量(压缩后 ~21kB,当然这里不包括markdown文档的大小)智能的全文搜索丰富的API支持Emoji,可以在文中添加表情兼容IE11支持服务端渲染SSR
docsify最大的好处就是可以让用户觉得自己是在以写博客的姿势写文档,反之亦然:以写文档的姿势写博客。Docsify学习成本低,部署简单,官方文档完善。原则上,它只需要了解markdown的语法和Node.js的安装。它对非IT从业者也非常友好。知名技术公众号main JavaGuide的网站是用docsify搭建的。下面简单介绍一下docsify的使用姿势。
安装docsify和初始化项目
Docsify是Node.js插件,需要提前安装Node.js。安装完成后,通过以下命令全局安装docsify:
NPI DOCSIFY-CLI-G复制代码假设磁盘中有一个/docsify-demo目录,其中的项目可以通过docsify init命令直接初始化:
#首先转到docsify-sample目录,在docsify-sample目录中打开命令行docsify init copy code命令。成功执行后,项目目录中将生成三个新文件,如下所示:
index.html为入口文件,css、js以及配置项都在此文件中修改。README.md会作为默认主页内容渲染。.nojekyll用于阻止GitHub Pages忽略掉下划线开头的文件。
然后调用docsify serve命令,访问http://localhost:3000进行本地预览。效果如下:
下面简单介绍docsify的功能时,使用的都是默认的配置参数。其实一般情况下,不建议修改默认配置项。
Docsify的配置项修改或者静态资源添加基本都是在index.html文件中操作,其他markdown文件(包括内置的侧边栏、封面文件和自己添加的文章)都是在运行时加载渲染的。
基本配置
基本配置项目如下:
& lt!DOCTYPE html & gt& lthtml lang = & # 34恩& # 34;& gt& lthead & gt& ltmeta charset = & # 34UTF-8 & # 34;& gt& lttitle & gt魔术docsify:& lt;div id = & # 34app & # 34& gt装货...</div & gt;& lt脚本& gt窗户。$docsify = {//项目名称:& # 39;docsify-demo & # 39;,//仓库地址。点击右上角Github上章鱼猫的图片,会跳转到这个地址repo:& # 39;https://github.com/zjcscut/docsify-demo',//侧边栏支持,默认加载项目根目录下的_sidebar.md文件loadsidebar: true,//导航栏支持,默认加载项目根目录下的_navbar.md文件loadnavbar: true,//cover支持,默认加载项目根目录下的_coverpage.md文件coverpage: true,//标题级别max level: 4,最大支持渲染。//自定义侧边栏后,默认不会生成目录。设置生成目录的最大级别,建议配置为1或2个子最大级别:2 } :& lt;脚本src = & # 34//cdn . jsdelivr . net/NPM/docsify/lib/docsify . min . js & # 34;& gt& lt/script & gt;& lt!- emoji表情支持-->:& lt;脚本src = & # 34//cdn . jsdelivr . net/NPM/docsify/lib/plugins/e moji . min . js & # 34;& gt& lt/script & gt;& lt!-图像放大和缩小支持->;& lt脚本src = & # 34//cdn . jsdelivr . net/NPM/docsify/lib/plugins/zoom-image . min . js & # 34;& gt& lt/script & gt;& lt!-搜索功能支持-& gt;& lt脚本src = & # 34//cdn . jsdelivr . net/NPM/docsify/lib/plugins/search . min . js & # 34;& gt& lt/script & gt;& lt/body & gt;& lt/html & gt;复制的代码中有更多的配置项。请参考docsify文档中的“定制-配置项”一节。越是定制的东西,越是难以维护。侧边栏、导航栏和封面都推荐采用默认的文件呈现方式:
组件sidebar /_sidebar.md导航栏/_ navbar . MD sidebar/_ cover page . MD
侧边栏与导航栏
需要在根目录下的index.html或_navbar.md文件中配置导航栏。你可以使用表情符号,并在这里修改index.html文件,例如:
& lt!——index.html->;& ltbody & gt& ltnav & gt& lta href = & # 34https://throwx . cn & # 34;& gt可扔的& # 39;的博客& lt/a & gt;& lta href = & # 34https://spring . throwx . cn & # 34;& gt弹簧柱
侧边栏需要在根目录下的_sidebar.md文件中进行配置。基本格式是:
*第一章标题*[第一章第一篇文章标题](第一章第一篇文章标题的降价文件)*[第一章第二篇文章标题](第一章第二篇文章标题的降价文件).......*第二章标题*[第二章第一篇文章标题](第二章第一篇文章标题的markdown文件)*[第二章第二篇文章标题](第二章第二篇文章标题的markdown文件)...复制代码渲染后的侧边栏效果是:
第一章标题-第一章第一篇文章标题-第一章第二篇文章标题-第二章第一篇文章标题-第二章第二篇文章标题复制代码,切换主题,只需切换根目录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正式文档的封面内容如下:
& lt!-_ cover page . MD-& gt;![logo](https://throwable-blog-1256189093 . cos . AP-Guangzhou . myq cloud . com/202009/_ media/icon . SVG)# docsify & lt;small & gt3.5 & lt/small & gt;& gt一个神奇的文件网站生成器。-简单轻量级(压缩后~ 21kb无需生成html文件-多主题【github】(https://github.com/docsifyjs/docsify/)【入门】(# docsify)复制代码渲染如下:
作者还参照这个配置做了一个很丑的主页,内容如下:
![logo](https://throwable-blog-1256189093 . cos . AP-Guangzhou . myq cloud . com/202009//leaf . SVG)#春天相册& ltsmall & gt0 . 0 . 1 & lt;/small & gt;& gt试着写一篇关于春天的专栏。这是原始版本,暂定包括以下栏目:-`SpringBoot 2.x `初学者系列-` Spring Boot 2.x `高级实用-`SpringBoot `源码系列【GitHub】(https://github.com/zjscut/spring-boot-guide)【入门】。
封面的内容可以用html或者markdown语法编写,自由度极高。
封面背景色随机切换,可以用![颜色](#f0f0f0)设置固定的背景颜色。
docsify项目部署
本文主要介绍GitHub页面和腾讯云COS的部署。其他类似于编码页面或者阿里云OSS的部署方式,可以参考下面介绍的两种方式进行部署。
部署在GitHub Pages
首先构建一个Github仓库,并将项目文件推上来:
点击右上角红圈的设置按钮,配置Github页面:
保存后配置自定义域名解析,即把域名解析成项目的Github页面,然后就可以通过自定义域名访问项目了。
当然,Github也为每个账号提供了一个免费的子域:account.github.io,需要命名为& # 34;账号. github . io & # 34;仓库,将项目文件推送到这个仓库,然后配置Github页面的属性来传递& # 34;账号. github . io & # 34;参观这个项目。
部署在腾讯云COS
笔者曾将一个子域名spring.throwx.cn解析到腾讯云COS的docsify项目中,过程非常简单。首先,创建一个对象存储桶,并将其设置为公共读取和私有写入:
然后将整个docsify项目中的文件复制到bucket中,index.html文件必须在bucket的根目录下:
那么静态网站中配置桶——索引文档(首页)的基本配置如下:
完成这一步后,就可以通过COS的公共域名访问docsify项目了。最后将子域解析为COS的内网域名,就可以通过自定义的子域名访问项目了。效果如下:
腾讯云新用户有六个月COS免费试用特权,建议早点试用。
小结
如果你喜欢markdown语法,又想以写博客的姿势写文档,或者以写文档的姿势写博客,可以试试docsify,你应该会喜欢这个优秀的开源工具。
参考资料:
docsify官方文档:https://docsify.js.org
项目仓库示例:
Github:https://github.com/zjcscut/docsify-demo
示例项目在线演示门户:
腾讯云:https://spring.throwx.cn
作者:Throwable
链接:https://juejin.im/post/6867923663879045127
免责声明:本站所有文章内容,图片,视频等均是来源于用户投稿和互联网及文摘转载整编而成,不代表本站观点,不承担相关法律责任。其著作权各归其原作者或其出版社所有。如发现本站有涉嫌抄袭侵权/违法违规的内容,侵犯到您的权益,请在线联系站长,一经查实,本站将立刻删除。
作者:美站资讯,如若转载,请注明出处:https://www.meizw.com/n/115651.html