最近一直在考虑吧工作环境往mac迁移,虽然很不适应!!
在制作api文档时被前端吐槽markdown太丑,不想看,不想对接,于是找了找一些比较美观的api文档制成方案,最后定位到gitbook。
查看本文的最好有一定的命令行基础,以及mac的一些基础操作,以及
确保已经安装了gitbook editor编辑器
1.安装node命令
安装成功后,使用node -v 确定正确
brew install node
可能遇到的问题:
什么什么usr什么什么 unwritable,大致的错误原因是brew等级太低了,就算执行了sudo chown -R $(whoami) /usr/xxx 也报错。这里不能重现了,总之重新安装homebrew即可
2.安装gitbook客户端
sudo npm install gitbook-cli -g
执行后,使用gitbook -V 查看版本,注意是大写的V
3.安装ebook-convert和calibre组件
sudo npm install ebook-convert -g
sudo npm install calibre -g
安装成功后,使用npm calibre -v和npm ebook-convert -v 确认版本成功安装
4.进入https://calibre-ebook.com/download 下载mac版calibre
直接使用npm安装的calibre好像还不够,我也不太清楚独立安装的和npm安装的到底是谁起作用了,反正3、4步我都干了
下载安装完成后,把安装文件夹里的calibre拖拽进入应用程序
默认安装的calibre会进入设备里,而不会进入程序,这一步很重要
5.添加ebook-convert仅path
sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin
如果提示file exist,请执行sudo rm /usr/local/bin/ebook-convert后再执行上述命令
请一定要删了重新放,已经存在的命令可能是旧的,或者是上述的步骤可能存在一些潜在的重复性操作输出了一个旧版的ebook-convert,这个问题将导致
InstallRequiredError: "ebook-convert" is not installed.
Install it from Calibre: https://calibre-ebook.com
这种问题。
6.最后一步,进入gitbook的书籍路径,执行
gitbook pdf . myproject.pdf
最后在该路径下生成了一个myproject.pdf的文件就是最终目标
请确保该路径下有可到达的md文件
如果要对pdf进行统一管理
进入一个目录,比如
mkdir projectsPDF
cd projectsPDF
gitbook pdf 拥有.md文件的绝对或者相对路径\. myproject.pdf
即会在projectsPDF下生成myproject.pdf,路径后面的点表示占位符,任意文件都会被扫描