官方介绍

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

这将非常实用,如果只是需要快速的搭建一个小型的文档网站,或者不想因为生成的一堆 .html 文件“污染” commit 记录,只需要创建一个 index.html 就可以开始写文档而且直接部署在 GitHub Pages。

(官网/演示): docsify

有的同学可能还不太明白它是干什么的,我简单说一下.
docsify,看名称就能大概知道是和文档有关的.
例如比较有名的 gitbook,就是一个文档写作平台,很多项目些教程文档的时候都会用到.
Snipaste_2019-10-17_14-51-14.png
但是gitbook在国内访问速度不行,并且收费.这时候就可以用docsify搭建一个属于自己的文档写作平台了.

可能有同学会问,我自己都搭建有博客了(如typecho/wp/emlog等),为什么不用博客直接写文档?
因为docsify或gitbook类的站点文档生产工具是使用js(vue之类的)以及html渲染的,优势有:

速度快!、体积小!、部署容易!、写作速度快!页面样式优雅简洁!、Markdown语法、代码高亮 等等!

Snipaste_2019-10-17_17-03-42.png
刚才上方的官方站点本身,就是使用docsify部署生成的,是不是很不错?

说了这么多,相信你对docsify已经有大致的了解,现在开始部署教程:

一、初始化项目(2选一)

  1. 使用 docsify-cli 工具

安装: npm i docsify-cli -g
初始化: docsify init ./docs # ./docs 初始化目录,可以更改

2.手动初始化

新建一个HTML文件,命名为 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>

现在就完成了项目的初始化.启用一个静态服务器即可访问(虽然是空白页).
index.html 是引导文件,现在我们需要新建几个后缀名为 .md 的文件
首页入口文件: README.md
导航栏文件: _navbar.md
侧边栏文件: _sidebar.md

后缀名 .md 文件统一使用 Markdown语法

项目配置项

打开编辑 index.html 文件

<script>
    window.$docsify = {
      //...配置项都写在这里面,默认空

      maxLevel: 3, //默认情况下会抓取文档中所有标题渲染成目录,可配置最大支持渲染的标题层级。默认6

      repo: 'https://github.com/docsifyjs/docsify/', //github仓库地址,会在页面右上角渲染一个 GitHub Corner 挂件。

      loadNavbar: true, //默认false 设置为true后,会加载_navbar.md文件渲染为导航栏,也可以自定义导航栏文件,把值改为文件名即可。

      loadSidebar: true, //定制侧边栏,说明同上
      subMaxLevel: 2, //自定义侧边栏后默认不会再生成目录,你也可以通过设置生成目录的最大层级开启这个功能。
      
      auto2top: true, //切换页面后是否自动跳转到页面顶部。

      homepage: 'home.md', //入口文件默认为: ```README.md``` , 通过此项可以自定义。

      basePath:'./', //文档加载的根路径,可以是二级路径或者是其他域名的路径。

      coverpage: false, //首页封面,默认false,开启后会加载_coverpage.md文件作为封面。

      logo: ./logo.png, //侧边栏Logo 默认是没有的

      name: "LittleMo s'blog", //文档标题,会显示在侧边栏顶部。

      nameLink: '/', //点击文档标题后跳转的链接地址。

      themeColor: '#3F51B5', 站点主题的颜色

      alias: {
          '/.*/_sidebar.md': '/_sidebar.md' // See #301
          //定义路由别名,可以更自由的定义路由规则。 支持正则。
      }

      loadSidebar: true,
      autoHeader: true, //同时设置 ```loadSidebar``` 和 ```autoHeader``` 后,可以根据 ```_sidebar.md``` 的内容自动为每个页面增加标题。

      mergeNavbar: true, //小屏设备下合并导航栏到侧边栏。

      formatUpdated: '{MM}/{DD} {HH}:{mm}', //显示文档更新日期,设置日期格式。

      notFoundPage: true, //在找不到指定页面时加载 ```_404.md``` ,可以自定义文件名

    }
</script>

找到上方JavaScript代码块,项目的所有配置都写在里面,默认为空.
更多配置项请到官方文档查看.

项目插件

  • 全文搜索 - Search
  • 谷歌统计 - Google Analytics
  • emoji
  • 外链脚本 - External Script
  • Demo code with instant preview and jsfiddle integration
  • 图片缩放 - Zoom image
  • 在 Github 上编辑
  • 复制到剪贴板
  • Disqus
  • Gitalk
  • Pagination
  • Code Fund

打开官网文档,进入插件介绍页查看即可,一般只需要引入一个js脚本,有些需要按说明添加配置项.

代码高亮

内置的代码高亮工具是 Prism ,默认支持 CSSJavaScriptHTML
如果需要高亮其他语言——例如 PHPpython 可以手动引入代码高亮插件。

index.html 文件底部引入js文件即可

<script src="//unpkg.com/prismjs/components/prism-php.min.js"></script>
<script sre="//unpkg.com/prismjs/components/prism-python.min.js"</script>

写法如下:
例1 php:
```php
echo "PHP是世界上最好的语言……";
```

例2 python:
```python
print("人生苦短,我用python")
```

按照上方写法即可得到你想要编程语言的高亮样式(得先引入js文件哦)
其他语言的js库文件:
https://unpkg.com/browse/prismjs/components/

到这里,docsify的部署使用就完成了.
还有没说的,如 .md 文件怎么写,这个会 Markdown语法 即可,下次弄个教程.
如果已经会 Markdown语法 的同学,请打开官方的代码仓库,查看导航栏/侧边栏等基本写法.

Vultr, 注册就送100$, 价格实惠, 服务器节点多多
最后修改:2019 年 10 月 18 日 01 : 18 AM
如果觉得我的文章对你有用,请随意赞赏