如何使用docsify编写文档

发表于 分类于 Disqus：
本文字数： 5.3k 阅读时长 ≈ 9 分钟

前言

目录说明

1
2
3
4
5
6
7
8
.
|-- README.md
|-- _coverpage.md
|-- _sidebar.md
|-- index.html
|-- _media
|   |-- Linux.ico
|   `-- linux-1.svg

从这个目录可以看出这个项目只需要几个md文件与一个html文件可以生产一个手册类项目，还是很方便的。

Quickly Start

准备MD手册文档

image-20210913155432399这里选择ansible practise

初始化docsify

1
2
touch ansiblepractise && cd ansiblepractise
docsify init ./

复制手册

image-20210913163538554

自动生成目录

1
2
3
4
5
工具：https://github.com/xxxxue/Docsify-Build-Sidebar/
修改工具配置文件
{
  "HomePath": "xxx\ansiblepractise"
}

运行工具

1
BuildSidebar>DocsifyBuildSidebar.exe

准备插件

docsify插件只要修改index.html文件即可。修改<title>内容即可。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
<!-- 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" />
    <title>修改</title>
    <link rel="icon" href="_media/Dakirby309-Simply-Styled-OS-Linux.ico" />
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/themes/vue.css" />

    <!-- 文件夹样式 -->
    <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar-folder.min.css" />
    <!-- 箭头样式 -->
    <!-- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/sidebar.min.css" /> -->
  </head>
  <body>
    <div id="app"></div>
    <script>  
      window.$docsify = {
        name: "Linux目录笔记",
        // 侧边栏文档目录
        loadSidebar: true,

        subMaxLevel: 2,
        alias: {
          "/.*/_sidebar.md": "/_sidebar.md",
        },
        // sidebarDisplayLevel: 1, // set sidebar display level
        // 跳转后自动到顶部
        auto2top: true,

        coverpage: true,
        // PLUGINS
        // ----------------------------------------------------------------
        // 页面右侧toc
        toc: {
          tocMaxLevel: 2,
          target: "h2, h3, h4, h5, h6",
        },

        // 全文搜索
        search: {
          depth: 6,
          noData: "没有搜到!",
          placeholder: "搜索...",
          // 避免搜索索引冲突,同一域下的多个网站之间
          namespace: "website-1",
        },
        // 底部导航
        pagination: {
          previousText: "上一页",
          nextText: "下一页",
          crossChapter: true,
          crossChapterText: true,
        },
        // 字数统计
        count: {
          countable: true,
          position: "top",
          margin: "10px",
          float: "right",
          fontsize: "0.9em",
          color: "red",
          language: "chinese",
          localization: {
            words: "",
            minute: "",
          },
          isExpected: true,
        },
      };
    </script>
    <!-- docsify -->
    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/docsify.min.js"></script>  

    <!-- 代码高亮  https://cdn.jsdelivr.net/npm/prismjs@1/components/ -->
	
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>	
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-python.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-cmake.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-csharp.min.js"></script>     
    <script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-docker.min.js"></script>  
	<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-powershell.min.js"></script>  


    <!-- 多tab支持 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-tabs@1/dist/docsify-tabs.min.js"></script>

    <!-- 代码复制 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-copy-code@2/dist/docsify-copy-code.min.js"></script>

    <!-- 底部 上一页下一页 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-pagination@2/dist/docsify-pagination.min.js"></script>

    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/external-script.min.js"></script>

    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/ga.min.js"></script>

    <!-- 全文搜索 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/search.js"></script>

    <!-- 图片放大缩小 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify@4/lib/plugins/zoom-image.min.js"></script>

    <!-- 字数统计 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-count@latest/dist/countable.min.js"></script>

    <!-- 侧边栏目录折叠 -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-sidebar-collapse/dist/docsify-sidebar-collapse.min.js"></script>

    <!-- 页面右侧 TOC -->
    <script src="https://cdn.jsdelivr.net/npm/docsify-plugin-toc@1.1.0/dist/docsify-plugin-toc.min.js"></script>
    
      <!-- emoji -->
      <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>
  </body>
</html>

运行

1
docsify serve

运行之后，可以看到结果

image-20210913164332348

但很明显还是比较凌乱的，所以需要进行修改目录文件，也就是_sidebar.md

可以一边运行，一边修改，从而更完善。

准备首页

对这个文件进行修改_coverpage.md

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<!-- _coverpage.md -->

<img src="_media/ansible.svg" alt="logo" style="zoom: 15%;" />

# Linux

> Ansible Practise

- 记录了我学习Ansible Practise的笔记
- 2021年/09月/13日



[GitHub](https://github.com/jsabook/testdocsify)
[Get Started](#SHELL)

增加SVG图标，_coverpage.md中使用svg文件。因此只要放在_mediａ目录下即可。

因此，特殊文件都被修改了

1
2
3
4
`-- docs
    |-- _coverpage.md
    |-- _sidebar.md
    |-- index.html

添加icon

做法一样，也是将图标放置于icon。

总结

1
2
3
4
`-- docs
    |-- _coverpage.md
    |-- _sidebar.md
    |-- index.html

图标文件放置于这个目录下

1
2
3
|-- _media
|   |-- Linux.ico
|   `-- linux-1.svg

如何改Icon？修改index.html文件

如何修改首页？修改_coverpage.md文件

插件如何增加？增加index.html