前端锦囊妙计

使用 simpler-paper 快速搭建文档系统指南

2017-11-29  本文已影响0人  WittBulter

第一次让我写文档时,我是拒绝的。因为写出来的文档压根没有人会认真看,我悄悄的在文档里面加上 Google Analytics 之后发现并没有人打开超过 3 页,他们只是看几页就不耐烦地对我流露出了然于胸的表情,像是在告诉我 『小子,你的文档我看过了,like shit !』

我把这些经历归结于自己的文档做的不够好,而且我明白了好的文档本身就不是给人看的,它的潜台词是告诉你,嘿,我的这个项目很叼,你知道吗?怀着这样的想法的我做了一个工具,让自己能在 5分钟之内生产出让别人闭嘴的文档,今天我也要告诉你该怎么用它。

先让我们看看效果:


预览

如果你觉得它不好看,那要赶紧关掉页面,因为这个文档系统还有两个更丑的主题。当然我也是求上进的,我请了一位设计师在为它设计新的样式。(设计师不鸽我的前提下)

Simpler Paper 是基于 NodeJS 运行的,如果你的电脑里没有 NodeJS,那么我建议你去下载一个试试。

  1. 安装与创建。
# 下载
npm i -g simpler-paper  
# 创建  
paper init

simpler-paper 会被安装在全局,在 paper init 时会在你的当前文件夹下创建一个文档文件夹,并且为你创建一个配置文件 paper.config.json。然后你就可以在这个文件夹下写点 markdown 文件 (xxx.md) 作为文档的内容啦
那如果你已经有了文档文件夹怎么办?按照命令的指引输入你文件夹的名字即可。

  1. 编译一个。
paper build

build 比较机智的地方在于它总是能自动找到你含有配置文件的地方进行编译,然后输出在指定位置。任何时候你完成编辑 markdown 后,来一句 paper build 总是感觉不错的!

  1. 预览一个。
paper server

在部署前你可以在本地看看文档编译后什么样,当然它也会自己去找编译输出的文件夹。

  1. 部署到 github 。
paper deploy

这就完了?是的。
deploy 后 simpler-paper 会做几件小事,把你的文件部署到 github 的 gh-pages 分支上,你只需要去项目里打开设置就能看到效果。(当然了,你的当前文件夹得是个 git 项目是吧)

好了现在看起来不错,你还可以在配置文件中指定主题、指示器、文档目录方式等等,这些以后可以再去看文档,当然也需你看完文档发现其中并没有多层目录、文件排列先后顺序、代码高亮的配置,这是因为我把它做成了约定。
多层目录的菜单结构是按文档的目录层次决定的,这是不用配置的。

我在项目里也写了更完善的文档,你可以去 github 看看。

先吹一下,我准备把它做成 50+ 主题的文档系统,如果你擅长 CSS 也可以去项目里贡献几个,不会也没有关系,毕竟也可以在 Issue 里拍拍脑袋,搞点需求出来嘛。
(写不下去了,感觉这篇文章也太水了……)

上一篇下一篇

猜你喜欢

热点阅读