登录
当前位置： 首页 > 工具软件 > Docsify > 使用案例 >

docsify操作和Docker部署流程文档

廉宇
2023-12-01

前言

根据官网介绍：
docsify是一个神奇的文档网站生成器。
docsify 会动态生成您的文档网站。与 GitBook 不同，它不会生成静态 html 文件。相反，它会智能地加载和解析您的Markdown文件，并将其显示为网站。要开始使用它，您需要做的就是创建一个索引 .html 并将其部署在 GitHub Pages 上。

当然我们也可以使用 Docker 非常方便的容器化部署。
内部 API 管理工具我们使用 yapi，但对于公开 API 获取和使用就不是很方便，所以对于有公开 API 文档需求的小伙伴来说，这正是一个非常优秀的查看和检索工具。

这里有一份 docker部署的 docsify 上的本文复刻版本 https://docsify.work.asrtts.cn/#/guide (点击查看)

下面本文会进行 docsify 的初始化、目录结构、部分功能介绍和部署介绍。
想部署快速验证可以直接看第七小节。

正文

本文档旨在帮助操作人员快速使用docsify构建文档，并完成相应的部署和测试。

一、初始化项目

1.1 安装node.js

下载地址：https://nodejs.org/

下载完成后点击安装

查看node版本，命令：

node -v

1.2 安装docsify-cli工具

推荐全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。

命令行执行：

npm i docsify-cli -g

1.3 初始化文档结构

创建一个本地文件夹docs作为编写文档的位置，执行命令：

docsify init ./docs

初始化成功后，./docs目录下会创建以下几个文件：

-| docs/
    -| .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件
    -| index.html 入口文件
    -| README.md 会做为主页内容渲染

直接编辑 docs/README.md 就能更新文档内容，也可以通过嵌入文件的方式添加内容。

例如，可以在README.md文件的末尾加上这一行：

[filename](../_media/example.md ':include')

example.md 文件的内容将会直接接续主页的末尾显示。

1.4 本地实时预览

在./docs目录的上级目录中执行命令：

docsify serve docs

即可启动一个本地服务器，可以方便地实时预览效果。默认访问地址为： http://localhost:3000

二、制作多页文档

2.1 多页面文档结构

如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。例如创建一个 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

2.2 定制侧边栏

默认情况下侧边栏会通过 Markdown 文件自动生成。如果要定制侧边栏，需要创建_sidebar.md文件，也可以自定义文件名。

首先需要修改index.html文件，配置loadSidebar选项：

<!-- index.html -->

<script>
    window.$docsify = {
        loadSidebar: true,//设置为 true 后会加载 _sidebar.md 文件
        loadSidebar: 'summary.md',//添加此项可以设置为自定义加载的文件名
        subMaxLevel: 2,//生成目录的最大层级，默认值为0，即自定义侧边栏后默认不会再生成目录
    }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

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

<!-- docs/_sidebar.md -->

* [首页](zh-cn/)
* [指南](zh-cn/guide)

此处需要 ./docs 目录下存在 .nojekyll 命名的空文件，用以阻止 GitHub Pages 忽略命名为下划线开头的文件。

2.3 嵌套的侧边栏

如果希望在浏览到一个目录时，只显示这个目录自己的侧边栏，可以通过在每个文件夹中添加一个 _sidebar.md 文件来实现这一点。

_sidebar.md 的加载逻辑是从每层目录下获取文件，如果当前目录不存在该文件则回退到上一级目录。例如当前路径为 /zh-cn/more-pages 则从 /zh-cn/_sidebar.md 获取文件，如果不存在则从 /_sidebar.md 获取。可以配置 alias 跳过此回退过程，直接读取文件。

<script>
    window.$docsify = {
        loadSidebar: true,
        alias: {
            '/.*/_sidebar.md': '/_sidebar.md'
        }
    }
</script>

也可以在一个子目录中创建一个 README.md 文件来作为此路由的默认页面。

2.4 页面标题

一个页面的 title 标签是由侧边栏中选中条目的名称所生成的，也可以设置为用侧边栏中选定的条目名称作为页面标题。

<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

三、定制导航栏

如果要定制导航栏，首先修改index.html文件，添加导航栏：

<!-- index.html -->

<body>
    <nav>
        <a href="#/">EN</a>
        <a href="#/zh-cn/">中文</a>
    </nav>
    <div id="app"></div>
</body>

接着需要配置loadNavbar：

<!-- index.html -->

<script>
    window.$docsify = {
        loadNavbar: true,//设置为true后会加载 _navbar.md 文件
        loadNavbar: 'nav.md',//添加此项可以自定义加载的文件名
    }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

然后创建需要加载的Markdown文件：

<!-- _navbar.md -->

* [En](/)
* [中文](/zh-cn/)

如果导航内容过多，可以写成嵌套的列表，会被渲染成下拉列表的形式。

<!-- _navbar.md -->

* 入门
    * [快速开始](zh-cn/quickstart.md)
    * [多页文档](zh-cn/more-pages.md)
    * [定制导航栏](zh-cn/custom-navbar.md)
    * [封面](zh-cn/cover.md)


* 配置
    * [配置项](zh-cn/configuration.md)
    * [主题](zh-cn/themes.md)
    * [使用插件](zh-cn/plugins.md)
    * [Markdown 配置](zh-cn/markdown.md)
    * [代码高亮](zh-cn/language-highlight.md)

_navbar.md 加载逻辑和 sidebar 文件一致，从每层目录下获取。

四、定制封面页

在index.html中添加封面页的配置：

<script>
    window.$docsify = {
        coverpage: true,//设置为true后会加载 _coverpage.md 文件
        coverpage: 'cover.md',//添加此项可以自定义加载的文件名

        coverpage: ['/', '/zh-cn/'],//也可同时设置多个页面的封面
        coverpage: {//也可同时设置多个封面并指定具体文件名
            '/': 'cover.md',
            '/zh-cn/': 'cover.md',
        },
    }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

添加_coverpage.md文件来配置封面页：

<!-- _coverpage.md -->

![logo](_media/icon.svg)

# docsify <small>3.5</small>

> 一个神奇的文档网站生成器。

- 简单、轻便 (压缩后 ~21kB)
- 无需生成 html 文件
- 众多主题

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#docsify)

目前的背景是随机生成的渐变色，也可以自定义背景色或者背景图。在文档末尾用添加图片的 Markdown 语法设置背景。

<!-- _coverpage.md -->

# docsify <small>3.5</small>

[GitHub](https://github.com/docsifyjs/docsify/)
[Get Started](#quick-start)

<!-- 背景图片 -->

![](_media/bg.png)

<!-- 背景色 -->

![color](#f0f0f0)

五、其他定制项

5.1 常规配置项

window.$docsify 里的配置项，除以上内容涉及的部分外，此处还将介绍一些常用的选项。详细内容请查看https://docsify.js.org/ 。

repo

配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件。默认值为null。

window.$docsify = {
    repo: 'docsifyjs/docsify',
    // or
    repo: 'https://github.com/docsifyjs/docsify/',
};

maxLevel

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

window.$docsify = {
    maxLevel: 4,
};

hideSidebar

这个选项用来完全隐藏侧边栏，侧边栏的任何内容都不会被渲染。默认值为true。

window.$docsify = {
    hideSidebar: true,
};

auto2top

设置切换页面后是否自动跳转到页面顶部。默认值为false。

window.$docsify = {
    auto2top: true,
};

homepage

设置首页文件加载路径。适合不想将 README.md 作为入口文件渲染，或者是文档存放在其他位置的情况使用。默认值为 README.md 。

window.$docsify = {
    homepage: 'home.md',//更改首页文件为/home.md
    homepage:
        'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',//更改为仓库地址
};

basePath

设置文档加载的根路径，可以是二级路径或者是其他域名的路径。

window.$docsify = {
    basePath: '/path/',

    // 直接渲染其他域名的文档
    basePath: 'https://docsify.js.org/',

    // 或者直接渲染其他仓库
    basePath:
        'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/',
};

relativePath

默认值为false。如果该选项设为 true ，那么链接会使用相对路径。

window.$docsify = {
    relativePath: true,//启用相对路径
};

例如目录结构如下时：

.
└── docs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        ├── guide.md
        └── config
            └── example.md

如果启用了相对路径，当前链接是 http://domain.com/zh-cn/README ，对应的链接会解析为：

guide.md              => http://domain.com/zh-cn/guide
config/example.md     => http://domain.com/zh-cn/config/example
../README.md          => http://domain.com/README
/README.md            => http://domain.com/README

logo && name && themeColor

logo是在侧边栏中出现的网站图标，可以使用CSS来更改大小。

name是文档标题，会显示在侧边栏顶部，也可以使用自定义 HTML 代码来方便地定制。

themeColor为主题色。

window.$docsify = {
    logo: '/_media/icon.svg',
    name: 'docsify',
    // or
    name: '<span>docsify</span>',
    themeColor: '#3F51B5'，
};

nameLink

点击文档标题后跳转的链接地址。默认值：window.location.pathname

window.$docsify = {
    nameLink: '/',

    // 按照路由切换
    nameLink: {
        '/zh-cn/': '/zh-cn/',
        '/': '/',
    },
};

alias

定义路由别名，可以更自由的定义路由规则。 支持正则。

window.$docsify = {
    alias: {
        '/foo/(.*)': '/bar/$1',
        '/zh-cn/changelog': '/changelog',
        '/changelog':
            'https://raw.githubusercontent.com/docsifyjs/docsify/master/CHANGELOG',
        '/.*/_sidebar.md': '/_sidebar.md',
    },
};

autoHeader

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

window.$docsify = {
    loadSidebar: true,
    autoHeader: true,
};

5.2 常用插件

此处介绍部分常用插件，详细内容请查看https://docsify.js.org/ 。

全文搜索 - Search

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

<script>
    window.$docsify = {
        search: 'auto', // 默认值

        search : [
            '/',            // => /README.md
            '/guide',       // => /guide.md
            '/get-started', // => /get-started.md
            '/zh-cn/',      // => /zh-cn/README.md
        ],

        // 完整配置参数
        search: {
            maxAge: 86400000, // 过期时间，单位毫秒，默认一天
            paths: [], // or 'auto'
            placeholder: 'Type to search',

            // 支持本地化
            placeholder: {
                '/zh-cn/': '搜索',
                '/': 'Type to search'
            },

            noData: 'No Results!',

            // 支持本地化
            noData: {
                '/zh-cn/': '找不到结果',
                '/': 'No Results'
            },

            // 搜索标题的最大层级, 1 - 6
            depth: 2,

            hideOtherSidebarContent: false, // 是否隐藏其他侧边栏内容

            // 避免搜索索引冲突
            // 同一域下的多个网站之间
            namespace: 'website-1',

            // 使用不同的索引作为路径前缀（namespaces）
            // 注意：仅适用于 paths: 'auto' 模式
            //
            // 初始化索引时，我们从侧边栏查找第一个路径
            // 如果它与列表中的前缀匹配，我们将切换到相应的索引
            pathNamespaces: ['/zh-cn', '/ru-ru', '/ru-ru/v1'],

            // 您可以提供一个正则表达式来匹配前缀。在这种情况下，
            // 匹配到的字符串将被用来识别索引
            pathNamespaces: /^(\/(zh-cn|ru-ru))?(\/(v1|v2))?/
        }
    }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

当执行全文搜索时，该插件会忽略双音符（例如，“cafe” 也会匹配 “café”）。像 IE11 这样的旧版浏览器需要使用以下 String.normalize() polyfill 来忽略双音符：

<script src="//polyfill.io/v3/polyfill.min.js?features=String.prototype.normalize"></script>

图片缩放 - Zoom image

在 index.html 文件中引入 zoom-image.min.js 即可：

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/zoom-image.min.js"></script>

鼠标放到一张图片上时会出现缩小或者放大的图标，点击后就可以改变图片的形态。

复制到剪切板

在所有的代码块上添加一个简单的Click to copy按钮来允许用户从你的文档中轻易地复制代码。在 index.html 文件中引入 docsify-copy-code 即可：

<script src="//cdn.jsdelivr.net/npm/docsify-copy-code/dist/docsify-copy-code.min.js"></script>

字数统计

提供统计中文汉字和英文单词的功能，并且排除了一些markdown语法的特殊字符例如*、-等。需要在 index.html 文件中引入 countable.js ：

<script src="//unpkg.com/docsify-count/dist/countable.js"></script>

同时添加count配置项：

window.$docsify = {
    count:{
        countable:true,
        fontsize:'0.9em',
        color:'rgb(90,90,90)',
        language:'chinese'
    }
}

代码高亮

docsify内置的代码高亮工具是 Prism。Prism 默认支持的语言如下：

Markup - markup, html, xml, svg, mathml, ssml, atom, rss
CSS - css
C-like - clike
JavaScript - javascript, js

添加额外的语法支持需要通过CDN添加相应的语法文件，比如需要添加java语法支持时:

<scriptsrc="https://cdn.jsdelivr.net/npm/prismjs@1.22.0/components/prism-java.min.js"></script>

要使用语法高亮，需要在代码块第一行添加对应的语言声明，示例如下:

```html
<p>This is a paragraph</p>
<a href="//docsify.js.org/">Docsify</a>
```

```java
System.out.println("hello");
```

5.3 Markdown 配置

内置的 Markdown 解析器是 marked，可以修改它的配置。同时可以直接配置 renderer。

window.$docsify = {
    markdown: {
        smartypants: true,
        renderer: {
            link: function() {
                // ...
            }
        }
    }
}

也可以完全定制 Markdown 解析规则:

window.$docsify = {
    markdown: function(marked, renderer) {
        // ...

        return marked
    }
}

六、文档语法扩展

docsify 扩展了一些 Markdown 语法，可以让文档更易读。详细内容查看https://docsify.js.org/ 。

6.1 强调内容

语法为 !> 内容

!> 一段重要的内容，可以和其他 **Markdown** 语法混用。

6.2 普通提示

语法为 ?> 内容

?> _TODO_ 完善示例

6.3 忽略编译连接

当需要在链接上加入相对路径时，需要防止docsify编译。例如：

[link](/demo/)

编译结果为 link ，并且会加载 /demo/README.md 。

[link](/demo/ ':ignore')

编译结果为 link，页面会跳转到 /demo/index.html 。

也可以为链接设置标题：

[link](/demo/ ':ignore title')

编译结果为 link

七、部署文档

7.1 Docker部署（官网修复版）

注：不知道什么原因官网所介绍的 docker 部署实例并不能通过，下面是多次测试验证后的修复版本。

  • 创建Dockerfile
FROM node:latest
WORKDIR /docsify
RUN npm install -g docsify-cli@latest --registry https://registry.npm.taobao.org docsify-cli@latest
ENTRYPOINT docsify init ./docs && docsify serve ./docs

构建 docker 镜像：

docker build -f Dockerfile -t docsify:1.0 .

运行 docker 镜像：

docker run -idt -p 3000:3000 -v /home/docsify:/docsify docsify:1.0
# -p 冒号前面的 3000 可以改成宿主机需要暴露的端口号 
# -v 冒号前面的 /home/docsify 可以改成宿主机文件存放地址

这时候去请求 domain:3000 就可以访问到页面了。

然后在宿主机下 /home/docsify/docs 即可看到 md 文件，修改文件后页面会即使生效，赞！

这里 /home/docsify 完全可以用 git 建个仓库管理下，当然用其他传文件方法也可以。

7.2 ZEIT Now部署

安装Now CLI：

npm i -g now

切换到 docsify 网站的文档目录：

cd docs

部署：

now

7.3 部署到GitHub Pages

提交代码到GitHub，将文档放在 docs/ 目录下，在设置页面开启 GitHub Pages 功能并选择 master branch /docs folder 选项。

7.4 部署到Gitee Pages

在对应的 Gitee 仓库服务中选择 Gitee Pages，选择要部署的分支，填写要部署的分支上的目录，例如docs，填写完成之后点击启动即可。

总结

如果有自己的服务器和域名，非常推荐使用 Docker 容器化部署方式，当然个人使用也可以直接使用 GitHub Pages 或 Gitee Pages，快速编写公开 API 之类的文档非常合适。喜欢本文可以关注我~有问题可以留言或私信我。

 类似资料：

相关阅读

springboot实现热部署操作方法Docker部署ElasticSearch和ElasticSearch-Head的实现部署docker-compose容器Docker 制作镜像Dockerfile和commit操作uwsgi+nginx部署Django项目操作示例

相关文章

文件上的操作7.2 Verilog 文件操作Gradle部署Flask部署redis部署

相关问答

Ktor和远程tomcat部署Java流操作Netbeans本地部署失败，而glassfish远程部署工作Spring boot应用程序从azure开发操作部署到appenginejavascript - docsify-cli？

相关文档

docsify 中文文档工作流程部署 kubernetes 集群Docker 中文文档如流智能工作台帮助文档
快捷导航： 新手教程 算法原理 架构设计 Java进阶 数据库进阶 大厂专栏 面试经验 编程笔记 编程问答 所有专题 文档资料 工具软件 电子书籍 小牛导航
在线工具： 房贷计算器 个税计算器 Linux命令查询 Json格式化 正则表达式 颜色转换 AES加解密 SHA1加密 MD5加密 毒鸡汤 字数统计 随机密码生成 进制转换 Base64编解码 励志句子
Copyright © 2019-2024 小牛知识库@xnip.cn. All Rights Reserved.