使用开源文档工具docsify，用写博客的姿势写文档

410 0 0

作者:Throwable

前提

下面的简介摘抄自docsify的官网 https://docsify.js.org 中的简介

docsify是一个神奇的文档网站生成器。他可以快速帮你生成文档网站。不同于GitBook、Hexo的地方是它不会生成静态的.html文件，所有转换工作都是在运行时。如果你想要开始使用他，只需要创建一个index.html就可以开始编写文档并直接部署在GitHub Pages（码云Pages、阿某云OSS或者鹅云COS等等）。它的主要特性如下：

无需构建，写完文档直接发布（运行时markdown文档转换）
容易使用并且轻量（压缩后 ~21kB，当然这里不包括markdown文档的大小）
智能的全文搜索
丰富的API
支持Emoji，可以在文中添加表情
兼容IE11
支持服务端渲染SSR

docsify的最大优势是可以让使用者感受到用写博客的姿势去编写文档，反过来说也行：用写文档的姿势去写博客。docsify的学习成本很低，部署简单，官方文档十分完善，原则上只需要理解markdown的语法和Node.js的安装即可，对于非IT技术从业者也十分友好。知名的技术公众号号主JavaGuide的站点就是采用docsify构建的。下文简单介绍docsify的使用姿势。

安装docsify和初始化项目

docsify是一个Node.js插件，所以需要提前安装Node.js。安装完毕后，通过下面命令全局安装docsify：

npm i docsify-cli -g

假设磁盘中有一个/docsify-demo目录，在该目录下可以直接通过docsify init命令初始化项目：

# 先进入docsify-sample目录，在docsify-sample目录打开命令行
docsify init

命令执行成功后，会在项目的目录生成三个新的文件如下：

index.html为入口文件，css、js以及配置项都在此文件中修改。
README.md会作为默认主页内容渲染。
.nojekyll用于阻止GitHub Pages忽略掉下划线开头的文件。

接着调用docsify serve命令然后访问http://localhost:3000即可进行本地预览，效果如下：

下面在简单介绍docsify的功能使用的时候，全部使用默认的配置参数，其实一般情况下，不太建议进行默认配置项的修改。

docsify的配置项修改或者静态资源增添基本都在index.html文件中操作，而其他markdown文件（包括内建的侧边栏、封面文件和自己添加的文章）都是运行时加载和渲染的。

基本配置

一份基本的配置项如下：

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="UTF-8">
    <title>神奇的docsify</title>
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <!-- 设置浏览器图标 -->
    <link rel="icon" href="/favicon.ico" type="image/x-icon" />
    <link rel="shortcut icon" href="/favicon.ico" type="image/x-icon" />
    <meta name="description" content="Description">
    <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <!-- 默认主题 -->
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
</head>

<body>
    <!-- 定义加载时候的动作 -->
    <div id="app">加载中...</div>
    <script>
        window.$docsify = {
            // 项目名称
            name: 'docsify-demo',
            // 仓库地址，点击右上角的Github章鱼猫头像会跳转到此地址
            repo: 'https://github.com/zjcscut/docsify-demo',
            // 侧边栏支持，默认加载的是项目根目录下的_sidebar.md文件
            loadSidebar: true,
            // 导航栏支持，默认加载的是项目根目录下的_navbar.md文件
            loadNavbar: true,
            // 封面支持，默认加载的是项目根目录下的_coverpage.md文件
            coverpage: true,
            // 最大支持渲染的标题层级
            maxLevel: 4,
            // 自定义侧边栏后默认不会再生成目录，设置生成目录的最大层级，建议配置为1或者2
            subMaxLevel: 2
        }
    </script>
    <script>
        // 搜索配置
        window.$docsify = {
            search: {
                maxAge: 86400000,
                paths: auto,
                placeholder: '搜索',
                noData: '找不到结果',
                depth: 4,
                hideOtherSidebarContent: false,
                namespace: 'docsify-demo',
            }
        }
    </script>
    <!-- docsify的js依赖 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
    <!-- emoji表情支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
    <!-- 图片放大缩小支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>
    <!-- 搜索功能支持 -->
    <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>
</body>

</html>

还有更多配置项可以参考docsify文档中的定制化 - 配置项一小节，定制的东西越多，维护的难度就越大。侧边栏、导航栏和封面都建议采用默认的文件渲染：

组件	文件
侧边栏	`/_sidebar.md`
导航栏	`/_navbar.md`
侧边栏	`/_coverpage.md`

侧边栏与导航栏

导航栏需要在根目录的index.html或者_navbar.md文件中配置，可以使用emoji，这里修改index.html文件如：

<!-- index.html -->

<body>
  <nav>
    <a href="https://throwx.cn">
    

  内容来源于网络如有侵权请私信删除
  

  
        
      文章来源: 博客园
  
      
      原文链接:
      
        https://www.cnblogs.com/throwable/p/13605289.html
      
    
  
       
        
 
  标签：
                        软件测试
              
        
         	
      
    
      
    
                


    
  
  
  
  


  

                
        	
    你还没有登录，请先登录或注册！
  

        
      还没有人评论，欢迎说说您的想法！

使用开源文档工具docsify，用写博客的姿势写文档