给 merger 新写的使用文档

大概是一个月以前,当时 @LF112 正在写他的新项目 lcookie,需要写使用文档。当时我毫不犹豫地向他推荐(并且帮他弄好了)Docsify 这个开源文档应用。

大概是半个月以前,我实在觉得 merger 写在 README 里面的中英双语文档质量太差了。因为当时写文档的时候是在修完最后一个 Bug 以后怀着激动的心情写的,所以遣词造句都有点太过口语化。并且中文文档是由英文直接翻译过来的,故此很多地方显得不通顺。思前想后,终于决定重写整个文档。

这一次我也是采用了 Docsify 作为文档系统。选择了先写中文文档,再写英文文档。

出乎我意料的是,Docsify 本身竟然还有一点点不够完善的地方。

Font-family

我惊奇地发现,Docsify 在英文浏览器下没有中文字体 Fallback,导致会被默认渲染成难看的宋体。下图为 Google Chrome 默认语言为英文 访客模式下的 Docsify 官方中文文档。

本来打算直接在 index.html 里面加 <style> 标签的,后来又发现 Docisfy 的 Vue.css 通过 Google Fonts @importSource San Pro 以及 Roboto Mono 的多个字重;我个人不喜欢加载不必要的字体和字重,所以就决定本地化 Vue.css 自己手动改。

<link rel="stylesheet" href="themes/vue.css" />
<!-- 从本地引用 -->
<link href="https://fonts.googleapis.com/css?family=Lato" rel="stylesheet" />
<!-- 直接在 index.html 内加载 Google Fonts -->
body,
input,
.docsify-copy-code-button {
  /* 这里为了不多开一个选择器 把后续添加的插件里缺少 'font-family' 的 'class' 也都加了进来 */
  /* font-family from Spectre.css */
  font-family: "Lato", -apple-system, system-ui, BlinkMacSystemFont, "Segoe UI",Roboto, "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Helvetica Neue";
}

.markdown-section code {
  font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, Courier, monospace; /* font-family from GitHub */
}

.markdown-section pre {
  font-family: SFMono-Regular, Consolas, Liberation Mono, Menlo, Courier, monospace; /* font-family from GitHub */
}

Google Fonts 字体方面选择了 Lato。中文 Font-family 一如既往选择了 Spectre.css 同样的方案codeFont-family 这次选择了 GitHub 的方案。

侧边栏和导航栏

按照官方文档:

window.$docsify = {
  // load from _navbar.md
  loadNavbar: true
};

在我这里没用。

机智如我:

window.$docsify = {
  loadNavbar: "_navbar.md",
  loadSidebar: "_sidebar.md"
};

搞定。

合并 js 请求

<script src="https://cdn.jsdelivr.net/combine/npm/[email protected],npm/[email protected]/lib/plugins/zoom-image.min.js,npm/[email protected]/lib/plugins/search.min.js,npm/[email protected],npm/[email protected]/dist/docsify-pagination.min.js,npm/[email protected]/components/prism-bash.min.js"></script>

jsDelivr 真香。

因为涉及到命令行代码块,这里里面加了个 prism-bash.min.js

其他样式修改

index.html 内新建一个 <sytle> 标签:

/* Prioritised Styles Here */
.pagination-item-label > * {
  line-height: 2;
  text-align: center;
}
.docsify-copy-code-button {
  font-size: 12px;
}

Service Worker

Docsify 支持 Service Worker

按照官方文档来即可:https://docsify.js.org/#/pwa?id=create-serviceworker;唯一需要注意的是因为我使用了 jsDelivr 代替 Unpkg,所以需要在官方给出的 sw.js 内作出相应的更改。

无法解决的问题

Docsify 支持自定义 homepage,可以用目录下任意一个 markdown 文件作为主页渲染。

homepage: 'index.md',

然而,因为 merger 的文档是双语文档,所以会有一个子目录 /en-gb

但是在这种情况下子目录并不可以设定自定义的 homepage 属性,只能用默认的 README.md。翻看了其他人提的 Issue,并没有找到解决方案。官方的方案是直接新建一个仓库然后远端渲染,但是这不是我想要的。


就这样,忙活了一天半,整个文档就写好了。

你现在可以通过 https://merger.hxco.dev 浏览 merger 的使用文档。

希望喜欢。

希望你也喜欢。虽然你不会。

窗外的天气阴郁而悲凉。

发表评论

电子邮件地址不会被公开。 必填项已用*标注

此站点使用Akismet来减少垃圾评论。了解我们如何处理您的评论数据