本来是不准备换掉 MDwiki 的,但自从看到友人 C 的 handsome 主题的文档使用了 docsify.js,看到了内置搜索功能以后,我立刻换掉了 MDwiki,这次我把我的折腾过程发出来分享。

难得五一假期有空发干货┑( ̄Д  ̄)┍,这里只介绍基本用法,具体用法请前往官网主页:https://docsify.js.org/#/zh-cn/

玉米:这是同逼官的节奏啊

因为。。。。。。这是玉米的文档:

1

这是我自己整的:

2

初始化 docsify.js

1,npm 初始化

npm i docsify-cli -g
docsify init ./docs

初始化成功后,可以看到 ./docs 目录下创建的几个文件

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

直接编辑 docs/README.md 就能更新网站内容,当然也可以 写多个页面

可使用以下命令本地预览,支持实时预览,默认访问 http://localhost:3000。更多命令行工具用法,参考 docsify-cli 文档

docsify serve docs

2,手动初始化(我就是用这种)

创建 index.html,在 index.html 下添加以下代码:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
  <div id="app"></div>
</body>
<script src="//unpkg.com/docsify"></script>
</html>

注意!:手动初始化时一定要手动创建 .nojekyll 文件阻止 GitHub Pages 忽略掉下划线开头的文件。

Loading 提示内容

初始化时会显示 Loading... 内容,你可以自定义提示信息。

<div id="app"> 加载中</div>

如果更改了 el 的配置,需要将该元素加上 data-app 属性(我没去改)。

<div data-app id="main"> 加载中</div>

  <script>
    window.$docsify = {
      el: '#main'
    }
  </script>

定制侧边栏由于我用不上,这里没有进行配置,因为默认情况下,侧边栏会根据当前文档的标题生成目录。

如有需要,请前往这里:https://docsify.js.org/#/zh-cn/more-pages

定制导航栏

为了完美迁移 MDwiki 的文档,我对配置进行了一些处理。

我们可以通过 Markdown 文件来配置导航。首先配置 loadNavbar,默认加载的文件为 _navbar.md。具体配置规则见 配置项#load-navbar(是的我没有直接通过 HTML 定制,因为文档很多)。

先在 index.html 添加以下代码(注意不在 body 标签内)

<script>
  window.$docsify = {
    loadNavbar: true
  }
</script>

然后就可以在文档根目录创建 _navbar.md 来自定义导航了:

这是我的_navbar.md 文件, 支持嵌套:

- [首页](/)

- GMS2 代购
  - [代购& 激活流程](/gms2.md)

- GM 插件文档
  - [CleanMem 文档](/cleanmem.md)
  - [GMThread 文档](/gmthread.md)
  - [GMZ 文档](/gmz.md)

- 玉米写的 GM 插件的文档
  - [MaizeMusic 文档](/maizemusic.md)
  - [MageINI 文档](/mageini.md)
  - [GM 语言包扩展文档](/gmu18n.md)
  - [GMSqlite 文档](/gmsqlite.md)
  - [JS 脚本解析器文档](/js.md) 
  - [NsfPlay 文档](/nsfplay.md) 

封面

封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 _coverpage.md 文件。渲染效果如本文档。

index.html 添加以下代码:

<script>
  window.$docsify = {
    coverpage: true
  }
</script>

在文档根目录创建_coverpage.md,这是我的_coverpage.md 文件:

# LiarOnce Wikis

> 一个高中学生的个人 Wiki

 - Pixiv ID : 61328141

[开始查阅](#liaronce-wikis)

![](../images/61328141_p0.jpg)

首页 logo 是支持自定义的,我没去加,这是代码请放在合适的位置(推荐放在一级标题之前):

![logo](_media/icon.svg)

更多配置

插件

此为 docsify.js 支持的所有插件:https://docsify.js.org/#/zh-cn/plugins

按照内容配置即可。

配置项

此为 docsify.js 的所有配置项:https://docsify.js.org/#/zh-cn/configuration

配置代码

这是我的配置代码,可以给你们借鉴一下:

<script> 
  window.$docsify = { 
    basePath: '/docs/', //文档加载的根路径 
    homepage: 'index.md', //首页文件加载路径 
    auto2top: true, //切换页面后是否自动跳转到页面顶部 
    maxLevel: 9999, //最大支持渲染的标题层级 
    coverpage: true, //启用封面页 
    loadNavbar: true, //加载自定义导航栏 
    mergeNavbar: true, //小屏设备下合并导航栏到侧边栏 
    name: 'LiarOnce Wikis', //文档标题 
    noEmoji: true, //禁用 emoji 解析(是的 emoji 我用不上)
    search: { //搜索功能 
        maxAge: 86400000, 
        paths: 'auto', 
        placeholder: '搜索', 
        noData: '找不到结果!' 
    } 
  } 
  //PWA 模式代码开始 
  if (typeof navigator.serviceWorker !== 'undefined') { 
      navigator.serviceWorker.register('sw.js') 
  } 
  //PWA 模式代码结束 
</script> 

效果地址:https://wiki.liaronce.win/

托管于 Coding 的项目地址:https://coding.net/u/liaronce/p/liaroncewiki/git


一个苦逼高中党的日常