docsify , 网站文档动态生成工具,类似gitbook

特性

  • 无需构建,写完文档直接发布
  • 容易使用并且轻量 (~19kB gzipped)
  • 智能的全文搜索
  • 提供多套主题
  • 丰富的 API
  • 支持 Emoji
  • 兼容 IE10+
  • 支持 SSR

安装

npm i docsify-cli -g

进入项目根目录并初始化

docsify init ./docs

之后docs目录下会生成以下几个文件

index.html 入口文件
README.md 会做为主页内容渲染
.nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件

运行服务

docsify serve ./docs

打开浏览器 http://localhost:3000

多页文档

创建多个页面,或者多级路由。创建一个 guide.md 文件,那么对应的路由就是 /#/guide。

例如这样一个目录结构

-| docs/
-| README.md
-| guide.md
-| zh-cn/
-| README.md
-| guide.md docs/README.md => http://domain.com
docs/guide.md => http://domain.com/guide
docs/zh-cn/README.md => http://domain.com/zh-cn/
docs/zh-cn/guide.md => http://domain.com/zh-cn/guide

设置封面

设置 coverpage 参数

window.$docsify = {
coverpage: true
}

接着在根目录创建 _coverpage.md 文件

背景自定义

默认的背景是随机生成的渐变色

如要自定义背景图片或者背景色,在_coverpage.md中设置如下内容

<!-- 背景图片 -->

![](_media/bg.png)

<!-- 背景色 -->

![color](#f0f0f0)

自定义导航栏

直接在 HTML 里定义导航栏,链接以 #/ 开头

在index.html的body中添加以下代码

<nav>
<a href="#/">EN</a>
<a href="#/zh-cn/">中文</a>
</nav>
<div id="app"></div>

接着配置 loadNavbar

window.$docsify = {
loadNavbar: true
}

在navbar.md_中添加以下链接

* [En](/)
* [中文](/zh-cn/)

侧边栏导航

默认侧边栏会根据当前文档的标题生成目录。也可以设置文档链接,通过 Markdown 文件生成

先配置 loadSidebar 选项

window.$docsify = {
loadSidebar: true
}

然后创建 _sidebar.md 文件,这样我们左侧目录就会显示出来

* [首页](zh-cn/)
* [指南](zh-cn/guide)

需要在文档根目录创建 .nojekyll 命名的空文件,阻止 GitHub Pages 忽略命名是下划线开头的文件。

插件

添加全文搜索

引入search.js

<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

配置search选项

search: {
maxAge: 86400000, // 过期时间,单位毫秒,默认一天
paths: [], // or 'auto'
placeholder: 'Type to search', // 支持本地化
placeholder: {
'/zh-cn/': '搜索',
'/': 'Type to search'
}, noData: 'No Results!', // 支持本地化
noData: {
'/zh-cn/': '找不到结果',
'/': 'No Results'
},
// 搜索标题的最大程级, 1 - 6
depth: 2
}

添加评论系统

Gitalk,一个现代化的,基于Preact和Github Issue的评论系统。

<link rel="stylesheet" href="//unpkg.com/gitalk/dist/gitalk.css">

<script src="//unpkg.com/docsify/lib/plugins/gitalk.min.js"></script>
<script src="//unpkg.com/gitalk/dist/gitalk.min.js"></script> <script>
const gitalk = new Gitalk({
clientID: 'Github Application Client ID',
clientSecret: 'Github Application Client Secret',
repo: 'Github repo',
owner: 'Github repo owner',
admin: ['Github repo collaborators, only these guys can initialize github issues'],
// facebook-like distraction free mode
distractionFreeMode: false
})
</script>

clientID和clientSecret需要在github上创建一个app生成

相关链接

docsify网站文档工具用法总结的更多相关文章

  1. 使用Docsify做文档网站的详细配置教程

    使用Docsify做文档网站的详细配置教程 作者:xhemj 没错,它叫Docsify. xhemj的文档中心就是用这个写的 开源地址:https://github.com/docsifyjs/doc ...

  2. API文档工具-Swagger的集成

    最近安装了API文档工具swagger,因为Github上已有详细安装教程,且安装过程中没有碰到大的阻碍,所以此文仅对这次安装做一份大致记录 相关网站 Swagger 官方地址: http://swa ...

  3. Javascript自动化文档工具JSDuck在Windows下的使用心得

    作者: zyl910 一.工具比较 为了让前端JavaScript程序更具可维护性,更利于团队开发,文档非常重要.此时便需要使用自动化文档工具了. 我对比了各种JavaScript自动化文档工具,发现 ...

  4. ShowDoc,APIDoc,可道云API,语雀-适合IT企业的文档工具

    ShowDoc,APIDoc,可道云API,语雀-适合IT企业的文档工具 一.ShowDoc官方文档及说明 1.1 它可以用来做什么 1.2 它都有些什么功能 1.3 使用在线的ShowDoc 1.4 ...

  5. 生成chm文档工具- Sandcastle -摘自网络

    Sandcastle是微软官方的文档生成工具,NDoc开发停止后,这个貌似也是唯一的一个这方面的工具.它从dll文件及其xml注释文件能够 生成完整的帮助文档,支持多种生成格式(Helpe1x:chm ...

  6. Spring Boot (十五): 优雅的使用 API 文档工具 Swagger2

    1. 引言 各位在开发的过程中肯定遇到过被接口文档折磨的经历,由于 RESTful 接口的轻量化以及低耦合性,我们在修改接口后文档更新不及时,导致接口的调用方(无论是前端还是后端)经常抱怨接口与文档不 ...

  7. JavaScript(3)——文档工具

    文档工具 LEARN HTML = 教程 HTML REFERENCE = 字典 HTML + CSS + JAVASCRIPT = DYNAMIC  HTML 推荐浏览器: Chrome浏览器(有丰 ...

  8. 使用开源文档工具docsify,用写博客的姿势写文档

    前提 下面的简介摘抄自docsify的官网 https://docsify.js.org 中的简介 docsify是一个神奇的文档网站生成器.他可以快速帮你生成文档网站.不同于GitBook.Hexo ...

  9. 文档工具GitBook使用

    一.登陆注册 地址:https://www.gitbook.com/ 1.gitbook可使用github账号登录,如果已经注册github可以直接使用github账号登录 2.如果是github账号 ...

随机推荐

  1. Codeforces Codeforces Round #484 (Div. 2) E. Billiard

    Codeforces Codeforces Round #484 (Div. 2) E. Billiard 题目连接: http://codeforces.com/contest/982/proble ...

  2. opencv2.4.13+python2.7学习笔记--OpenCV中的图像处理--图像轮廓特征和几何矩

    阅读对象:对概率论中的期望有一点了解. 1.图像几何矩 1.1简述 图像的几何矩包括空间矩.中心矩和中心归一化矩.几何矩具有平移.旋转和尺度不变性,一般是用来做大粒度的区分,用来过滤显然不相关的图像. ...

  3. APIView源码简单分析图

    APIView源码简单分析 !声明:下面这个dispatch分发方法不在是父类View里的dispatch了,APIView重新封装了这个dispatch.(整个核心就是initialize_requ ...

  4. Appium之xpath定位元素

    原文:http://www.cnblogs.com/cnkemi/p/9180525.html appium也是以webdriver为基的,对于元素的定位也基本一致,只是增加一些更适合移动平台的独特方 ...

  5. Linux系统安装 OpenSSL两种方法

    OpenSSL是一个开源的ssl技术,由于安装pytbull,需要安装openssl,并下载对应的版本下载地址:https://www.openssl.org/source/ 方法一,编译安装Open ...

  6. HDFS-HA高可用

    HDFS-HA工作机制 通过双NameNode消除单点故障 HDFS-HA工作要点 1.元数据管理方式需要改变 内存中各自保存一份元数据: Edits日志只有Active状态的NameNode节点可以 ...

  7. 【转载】ARCHIVE_LAG_TARGET参数的作用(定时切换redo)

    (一)  设置archive_lag_target参数1.      一旦设置了archive_lag_target初始化参数,数据库将会周期性的检查实例的当前重做日志.如果遇到下列情况,实例将会切换 ...

  8. 学习Java的进度

    这周我们通过老师的讲解带着我们回到了第八周的知识点.lambda表达式也是一种简化程序的好方法,通过回调程序的测试可以对比出lambda 表达式少的不是一两行代码,可以少了类中方法的定义,直接使用.内 ...

  9. [转] Introduction to AppArmor

    Introduction to AppArmor http://ubuntuforums.org/showthread.php?t=1008906 Contents Post 1 Introducti ...

  10. python写的压缩软件

    import tkinterimport tkinter.filedialogimport osimport zipfileimport tkinter.messagebox #创建住窗口root = ...