docsify一个神奇的文档生成工具

更新日期: 2019-06-24阅读: 2.6k标签: 文档

在开发项目时,我们或许需要一份精致的开发文档,那么使用docsify是不错的选择,docsify是一个文档生成工具,它直接加载 Markdown 文件并动态渲染,同时还可以生成封面页。所以我们只需要写完 Markdown 文档,就可以看到文档页面了。


特性

无需构建无需编译,写完markdown文档直接发布

容易使用并且轻量 (~18kB gzipped)

智能的全文搜索

提供多套主题

丰富的 api

支持 Emoji

兼容 IE10+

支持 SSR (example)


快速上手

我们直接创建一个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>

新建README.md文件,作为主页面,编辑:

# Title

## balabala

如果你系统安装了web服务器的话,直接运行web服务,比如我使用php,命令行直接启动web服务。

php -S localhost:3000

然后直接在浏览器打开localhost:3000,就可以看到基本的网页框架了。接下来我们就需要写文档了。

当然你也可以直接把构建好的文档放到你的web服务器上,比如nginx、apache或者IIS上预览。

我们也可以安装官方提供的docsify-cli工具,可以方便创建及本地预览文档网站

npm i docsify-cli -g
docsify init ./docs
docsify serve docs

docsify提供 LiveReload 功能,可以让实时的预览,默认访问localhost:3000。


多页面

README.md作为主页面,如果需要创建多个页面,或者需要多级路由的网站,在 docsify 里也能很容易的实现。直接在文档目录下创建对应的 *.md 文件,例如创建一个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

定制侧边栏

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

首先配置loadSidebar选项。

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//unpkg.com/docsify"></script>

接着创建 _sidebar.md 文件,内容如下

- [安装](install.md)
- [介绍](guide.md)

然后只要在对应的install.md和guide.md两个文件中写内容就OK了。当然这两个文档都是Markdown格式的,需要按照markcodown语法来编辑。markcodown语法很简单,百度一把,十分钟入门,半小时精通。


主题

目前提供三套主题可供选择,模仿 Vue 和 buble 官网订制的主题样式。还有 @liril-net 贡献的黑色风格的主题。直接修改index.html中的css链接即可。

<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/pure.css">


全文搜索

docsify支持全文搜索,docsify会根据当前页面上的超链接获取文档内容,在 localStorage 内建立文档索引。默认过期时间为一天,当然我们可以自己指定需要缓存的文件列表或者配置过期时间。


<script>
  window.$docsify = {
    // 完整配置参数
    search: {
      maxAge: 86400000, // 过期时间,单位毫秒,默认一天
      paths: 'auto',
      placeholder: '搜索',
      noData: '没有记录!'
    }
  }
</script>
<script src="//unpkg.com/docsify"></script>
<script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

运行后,我们在页面的左上角会有一个搜索框,支持全文搜索的。

想了解更多有关docsify的配置和应用,请访问项目官网:docsify


链接: https://fly63.com/article/detial/7004

docsify - 生成文档网站简单使用教程

docsify 是一个动态生成文档网站的工具。不同于 GitBook、Hexo 的地方是它不会生成将 .md 转成 .html 文件,所有转换工作都是在运行时进行。

DTD文档模型是什么?

DTD文档模型是DOCTYPE文档声明,是Doucument Type Definition的英文缩写,是文档类型定义;制作一个标准的页面,声明一个正确的DOCTPYE,HTML里面的标识和CSS才能正常生效.

撰写后台需求文档需要注意的那些事儿

很多产品经理在撰写后台的需求文档时会一脸懵,很多时候不知道怎么开始,这篇文章主要根据自己工作中对后台的理解和需求文档撰写经验进行分享。人员较小的公司,会要求产品经理后台管理和前台界面一起进行撰写。

程序员为什么不写文档?

为什么程序员不写文档?是不想写吗?最近,资深软件工程师 Kislay Verma 分析了背后的深层原因。他认为软件工程师不写文档有以下两个主要原因。

React新文档:不要滥用Ref哦~

React新文档有个很有意思的细节:useRef、useEffect这两个API的介绍,在文档中所在的章节叫Escape Hatches(逃生舱)。显然,正常航行时是不需要逃生舱的,只有在遇到危险时会用到。

程序员应该写文档吗?

80% 的文档都是无效的,所以多数情况下,程序员都不用写文档,原因如下:多数文档都是代码的点缀或者静态的记录已经实现的代码,懂代码的开发人员会直接看代码,不懂代码的开发人员压根不会看。

为什么几乎所有技术文档读起来都非常难受?

我们学习一个新接触的文档时,常常觉得非常难受,而自己消化了再写教程就非常舒服,这会让人产生一种错觉,就是官方文档没好好写。那么实际上,官方文档为什么长期以来,难以代替第三方教程的存在呢?

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!