docsify安装,docsify搭建,docsify使用教程

docsify安装,docsify搭建,docsify使用教程

首先安装docsify-cli脚手架，用于初始化docsify文档项目

npm i docsify-cli -g

然后初始化

docsify init ./docs

初始化后

目录结构如下所示

• index.html 入口文件
• README.md 会做为主页内容渲染
• .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件 (.后缀结尾的是隐藏文件)

启动

在我们使用init命令初始化一个文档后，我们需要通过下面命令运行一个本地服务器

docsify serve

项目启动后，默认访问 http://localhost:3000 ，如下图所示，我们能够看到一个帮助文档的骨架了

同时docsify还提供了LiveReload功能，也就是可以在我们修改文档后，能够实时预览

编辑

修改Loading

初始化时会显示 Loading… 内容，你可以自定义提示信息，我们只需要修改index.html中的

标签即可，在里面加入我们需要的提示内容

定制侧边栏

默认情况下，侧边栏会根据当前文档的标题生成目录，也可以通过设置文档链接，通过Markdown文件生成，效果如当前的文件的侧边栏，首先我们在index.html里面进行设置

    window.$docsify = {
      loadSidebar: true, // 设置侧边栏
    }

然后新增一个markdown文件_sidebar.md ,

设置封面

docsify默认是没有封面的，默认有个首页./README.md。
通过设置coverpage参数，可以开启渲染封面的功能。

首先需要在index.html文件中的window.$docsify添加coverpage: true选项：

  window.$docsify = {
    coverpage: true
  }

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

自定义封面背景

目前的背景是随机生成的渐变色，每次刷新都会显示不同的颜色。
docsify封面支持自定义背景色或者背景图，在_coverpage.md文档末尾添加：

<!-- 背景图片 -->
![](_media/bg.png)

<!-- 背景色 -->
![color](#2f4253)

注意：

• 自定义背景配置一定要在_coverpage.md文档末尾。
• 背景图片和背景色只能有一个生效.
• 背景色一定要是#2f4253这种格式的。

封面作为首页

配置了封面后，封面和首页是同时出现的，封面在上面，首页在下面。通过设置onlyCover参数，可以让docsify网站首页只显示封面，原来的首页通过http://localhost:3000/#/README访问。在index.html文件中的window.$docsify添加onlyCover: true,选项：

  window.$docsify = {
    coverpage: true,
    onlyCover: true,
  }

通过此配置可以把./README.md文件独立出来，当成项目真正的README介绍文件

搜索插件

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

<script>
    window.$docsify = {
      // 完整配置参数
      search: {
        maxAge: 86400000,               // 过期时间，单位毫秒，默认一天
        paths: [],                      // or 'auto'，匹配文件路径
        placeholder: 'Type to search',  // 搜索提示框文字， 支持本地化，例子在下面
        // placeholder: {
        //   '/zh-cn/': '搜索',
        //   '/': 'Type to search'
        // },
        noData: 'No Results!',          // 找不到结果文字提示，支持本地化，例子在下面
        // noData: {
        //   '/zh-cn/': '找不到结果',
        //   '/': 'No Results'
        // },
        depth: 2,                       // 搜索标题的最大程级, 1 - 6
      }
    }
  </script>
  <!-- 引入搜索模块 -->
  <script src="//unpkg.com/docsify/lib/plugins/search.js"></script>

安装后，我们就能够使用搜索功能了