Wiki系列(二):docsify部署及配置
in 佳软推荐 with 33 comment

Wiki系列(二):docsify部署及配置

in 佳软推荐 with 33 comment

上一篇文章选出了 docsify 作为我的 Wiki 系统,这篇就来说下 docsify 的部署和配置。

官方推荐部署

docsify 快速开始文档:https://docsify.js.org/#/quickstart

快速开始

安装 docsify-cli 工具:

npm i docsify-cli -g

初始化项目:

docsify init ./docs

预览网站:

docsify serve docs

部署到服务器

docsify 部署文档:https://docsify.js.org/#/deploy

可以选择部署到以下服务:

我自己的部署

初始化项目

我在本地使用官方的构建工具进行初始化项目:

docsify init wiki

初始化之后其实有三个文件,index.htmlREADME.md.nojekyll

在本地编辑好文档,通过下面命令即可本地预览:

docsify serve wiki

上传到Git

添加了文档之后,我将整个 wiki 文件夹上到了「 Gitee」,为什么选 Gitee 呢,当然是国内访问快而且免费了。

部署到Nginx

登陆我的服务器,生成 SSH 公钥,生成方式可以参考「生成/添加SSH公钥」,然后添加到 Gitee 的 「SSH 公钥」。

然后在服务器使用 git 拉取 Wiki 项目,当然要使用 SSH 地址,以后本地文档更新推送到 Gitee 之后,只要在服务器上拉取更新就可以了。

拉取之后,配置 Nginx 如下,即可通过域名访问:

server {
  listen 80;
  server_name  wiki.juemuren4449.com;
    location / {
      try_files $uri $uri/ /index.html;
      root /usr/local/wiki;
      index  index.html index.htm;
      add_header Cache-Control "no-cache, no-store";
  }
}

设置不缓存这个因人而异,我个人的 Wiki 刚开始积累,还在不断的完善,如果允许缓存,可能导致最新更新的内容不显示,等以后趋于完善,应该会设置允许缓存,或者直接放到 CDN 上。

为什么没用CDN

由于 docsify 搭建的 Wiki 都是源文件,不需要自己编译,所以完全可以把整个文档放到又拍云或者七牛云等 CDN 上,访问速度会更快。

但目前我还是把 Wiki 部署到了我的服务器上,为什么不直接放到 CDN 上呢,有以下几个原因:

如果使用默认的 routerMode,放在 CDN 上完全可行。

自定义配置

docsify 自定义配置文档:https://docsify.js.org/#/configuration

各项配置都在 window.$docsify 里。

我添加了如下配置,更多配置请参考上方文档链接。

loadSidebar

加载自定义侧边栏,具体可以参考 https://docsify.js.org/#/more-pages

loadSidebar: true,

增加 _sidebar.md 文件,编写文件格式如下:

- [CentOS](centos.md)
- [Docker](docker.md)
- [Mac](mac.md)
- [NPM](npm.md)
- [推荐](recommend.md)

subMaxLevel

自定义侧边栏后默认不会再生成目录,需要通过设置生成目录的最大层级开启这个功能。

subMaxLevel: 2,

配合 loadSidebar,效果如下:

subMaxLevel

auto2top

切换页面后是否自动跳转到页面顶部。

auto2top: true,

name

文档标题,显示在侧栏顶部。

name: '掘墓人的 Wiki',

nameLink

点击文档标题后跳转的链接地址。

nameLink: '/',

点击后跳转到 Wiki 首页。

routerMode

设置路由模式。

routerMode: 'history',

设置为 history 之后,浏览器链接里不会出现 #,个人习惯。

注意,设置为 history,如果使用的是 Nginx 部署的项目,一定要加上下面的配置,否则在非首页刷新会找不到页面。

try_files $uri $uri/ /index.html;

coverpage

设置是否启用封面页,默认不启用。

我没有启用封面,因为我的 Wiki 不涉及到宣传,就是自己查阅,所以应该打开就可以看到内容。

不过 docsify 的封面还是很好看的。

docsify

topMargin

让你的内容页在滚动到指定的锚点时,距离页面顶部有一定空间。

topMargin: 40,

设置之后,点击侧栏的二级标题之后,页面的标题不会距离顶部太近。

插件

docsify 插件文档:https://docsify.js.org/#/plugins

docsify 有丰富的插件,可以按需添加。

Full text search

全局搜索

search: {
  paths: 'auto',
  placeholder: '请输入要搜索的关键字',
  noData: '没有结果',
  depth: 6,
},

开启全局搜索需要引入两个 js 文件:

<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>

效果如下:

Full text search

Copy to Clipboard

复制到剪贴板,在所有的代码块上添加一个简单的 Copy to Clipboard 按钮来允许用户从你的文档中复制代码。

需要引入 js 文件:

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

效果如下:

Copy to Clipboard

Pagination

分页导航,在文档的最下方会展示上一个文档和下一个文档。

pagination: {
  previousText: '上一章节',
  nextText: '下一章节',
}

需要引入两个 js 文件:

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

效果如下:

Pagination

关于js文件

插件需要引入 js 文件,为了访问更稳定,我把所有的 js 文件都上传到了又拍云。

截止到发文,docsify 的最新版本是 4.11.3,查询更多版本请查看「docsify releases」。


以上就是 docsify 部署及配置的全部内容了,更多详细说明,可以查看「docsify 文档」。

最后附上我的 Wiki 地址:掘墓人的 Wiki,欢迎查阅。

掘墓人的Wiki

相关阅读:

Wiki系列(一):Wiki系统选择

33评论
  • Microcharon

    请问博主有没有关于改善docsify的seo的方法

    • 掘墓人 博主

      @Microcharon docsify 本身对 SEO 就不友好,如果在意的话可以换其他的 Wiki 项目。

  • vv

    index.html的window.$docsify配置,以及Nginx也用您同样的配置。
    也是用了路由模式,没加CDN。
    打开首页,加载自定义侧边栏,正常,但点击侧边栏后的文章后,
    加载自定义侧边栏,一直显示,Loading.…

    求解,谢谢

    • 掘墓人 博主

      @vv 看一下浏览器控制台的报错信息,排查一下

      • vv

        @掘墓人 看了下 没错误呢,奇怪了

      • vv

        @掘墓人 搞定了,只需在index.html的window.$docsify配置routerMode: 'history'

        看到文章中,注意,设置为 history,如果使用的是 Nginx 部署的项目,一定要加上下面的配置,否则在非首页刷新会找不到页面。
        try_files $uri $uri/ /index.html;
        加了这个配置反而不行。屏蔽之后测试正常。谢谢回复,学到不少东西

        • 掘墓人 博主

          @vv 好的,晚点我也看下我的配置

          • vv

            @掘墓人 好的,谢谢,您忙完后,麻烦回复下配置,我看下是不是这个问题导致的。

          • vv

            @掘墓人 重新排查了下,还是有点问题,在Nginx配置中,去掉try_files $uri $uri/ /index.html;
            加载自定义侧边栏,正常。唯一问题就是去掉#之后,从主页阅读文章,正常,但是如果刷新,URL 就不对了。404,能理解。
            但加上try_files $uri $uri/ /index.html;配置之后,自定义侧边栏,为空白,而正文内容,一些样式也变成 默认404页面的样式。挺怪异,不知道哪里问题,控制台也没错误。请指点下,您忙完后发下您的配置,我对比下

            • 掘墓人 博主

              @vv nginx 配置
              location / {
              proxy_set_header Host $http_host;
              proxy_set_header X-Forward-For $remote_addr;
              proxy_set_header X-Real-IP $remote_addr;
              proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
              proxy_set_header X-Forwarded-Proto $scheme;
              try_files $uri $uri/ /index.html;
              root /usr/local/wiki;
              index index.html index.htm;
              add_header Cache-Control "no-cache, no-store";
              }

              index.html:

              window.$docsify = {
              // 配置
              loadSidebar: true,
              subMaxLevel: 2,
              auto2top: true,
              name: '掘墓人的 Wiki',
              nameLink: '/',
              routerMode: 'history',
              topMargin: 40,

              // 插件
              search: {
              paths: 'auto',
              placeholder: '请输入要搜索的关键字',
              noData: '没有结果',
              depth: 6,
              },
              pagination: {
              previousText: '上一章节',
              nextText: '下一章节',
              }
              }

              • vv

                @掘墓人 谢谢,已经找到解决方案了:https://github.com/docsifyjs/docsify/issues/1713
                加了别名就搞定了

                • 掘墓人 博主

                  @vv 大拇指.png

  • 澍梵

    请教下,设置了搜索框但是出现了两个搜搜框。这个怎么处理。

    • 掘墓人 博主

      @澍梵 把搜索框配置去了试下,或者检查下是否有两个配置。

      • 澍梵

        @掘墓人 请问配置是好的,但是点击主页的开始阅读,不跳转到内容页式怎么回事,url地址倒是变换了就是不进内容页。

        • 掘墓人 博主

          @澍梵 这个得看下文档了,我没设置主页,直接就是内容页。

          • 澍梵

            @掘墓人 loadNavbar: true, //开启导航栏
            coverpage: true, //开启封面
            loadSidebar: true,//开启侧边栏
            auto2top: true, //切换页面自动回到顶部
            subMaxLevel: 2, //目录最大级数
            maxLevel: 4, //可配置最大支持渲染的标题层级
            mergeNavbar: true,//小屏设备下合并导航栏到侧边栏。
            //添加搜索功能,中文和英文文档同时搜索
            难道是这几个其中有冲突项?

            • 掘墓人 博主

              @澍梵 不确定,可以试下删除其他配置,一个个测试。

          • 澍梵

            @掘墓人 https://gitee.com/shufan1/docsify_web
            这个是项目的地址

  • 志花

    大佬,怎么去除广告呢

    • 掘墓人 博主

      @志花 默认没有广告啊,参考官方文档看一下。

      • 志花

        @掘墓人 很奇怪,左上角,搜索的下面,老是会弹出小广告

        • 掘墓人 博主

          @志花 在配置里搜一下,有没有 carbon 相关的内容,应该就是导致广告的原因。也可以挨个检查插件或者引入的 js 文档进行排查。

          • 志花

            @掘墓人 好的,谢谢。再请教下,如果我想建多个项目需要怎么弄呀?(现在按照官方文档,docs一个项目。想建其他的)

            • 掘墓人 博主

              @志花 多个项目就部署多个环境多个域名,也可以直接通过目录来区分项目

              • 志花

                @掘墓人 我再docs目录下,新建了子项目。比方:\docs\masterlab
                把README.md、_sidebar.md、还有其他写好的.md文件放在masterlab目录下。
                但是链接过去,http://xxx:3000/#/MasterLab/README.md。能显示内容。但是点击侧边栏的导航,就会提示404 - Not found

                _sidebar.md(内容如下)

                - [介绍](Private-deployment.md)

                - [私有化部署](Private-deployment.md)

                - [常见问题](common-problem.md)

                - [名词解释](Noun-interpretation.md)

                我是哪里理解的不对吗,麻烦大佬帮忙看下。

                • 掘墓人 博主

                  @志花 我的两个方案,供参考:
                  1、把每个项目单独进行部署,各自是各自的,域名和目录都是各自的,不要通过子文件夹区分项目。
                  2、只部署一个 docsify,每个项目就是一个 md 文件,直接通过 md 文件区分即可。例如你的例子, masterlab 项目就是一个 md 文件,将介绍、私有化部署、常见问题等都写到这个文件里;其他项目也类似,新建一个 md 文件就可以了。

                  • 志花

                    @掘墓人 明白了,谢谢你

                    • 掘墓人 博主

                      @志花 不客气

  • lei

    大佬 docsify如何部署到自己服务器上呢?

    • 掘墓人 博主

      @lei 这篇不就是写我怎么部署的么😂

  • klz

    大佬,请问评论怎么加呀

    • 掘墓人 博主

      @klz https://docsify.js.org/#/zh-cn/plugins?id=disqus
      https://docsify.js.org/#/zh-cn/plugins?id=gitalk
      这两个可以看下