2. GitBook
效果:
效果详情请看:http://biaochenxuying.cn:2021。
2.1 GitBook 常用指令
- 安装 GitBook:
npm i gitbook-cli -g
- 初始化 GitBook 项目:
gitbook init
- 安装 GitBook 依赖:
gitbook install
- 开启 GitBook 服务:
gitbook serve
- 打包 GitBook 项目:
gitbook build
- GitBook 命令行查看:
gitbook -help
- GitBook 版本查看:
gitbook -V
2.2 简单上手
然后,我们找个空文件夹,初始化一个 GitBook 项目。
gitbook init
初始化 README.md 和 SUMMARY.md 两个文件.gitbook build
本地构建但不运行服务,默认输出到 _book/ 目录.gitbook serve
本地构建并运行服务,默认访问 http://localhost:4000 实时预览.
- GitBook - README.md - SUMMARY.md
README.md
是默认首页文件,相当于网站的首页index.html
,一般是介绍文字或相关导航链接.SUMMARY.md
是默认概括文件,主要是根据该文件内容生成相应的目录结构,同README.md
一样都是被gitbook init
初始化默认创建的重要文件._book
是默认的输出目录,存放着原始markdown
渲染完毕后的html
文件,可以直接打包到服务器充当静态网站使用。一般是执行gitbook build
或gitbook serve
自动生成的.book.json
是配置文件,用于个性化调整gitbook
的相关配置,如定义电子书的标题、封面、作者等信息。虽然是手动创建但一般是必选的.GLOSSARY.md
是默认的词汇表,主要说明专业词汇的详细解释,这样阅读到专业词汇时就会有相应提示信息,也是手动创建但是可选的.LANGS.md
是默认的语言文件,用于国际化版本翻译和GLOSSARY.md
一样是手动创建但是可选的.
book.json 的意思:
title
:网站标题author
:网站作者description
:网站功能描述language
:网站使用语言styles
:网站额外配置的样式表plugins
:网站使用的插件pluginsConfig
:网站使用的插件的额外配
笔者的 book.json
:
{ "title": "夜尽天明的博客", "author": "biaochenxuying", "description": "大前端技术为主,读书笔记、随笔、理财为辅,做个终身学习者。", "language": "zh-hans", "plugins": [ "-highlight", "copy-code-button", "search-pro", "-search", "-lunr", "expandable-chapters", "splitter", "-sharing", "github-buttons", "donate", "tbfed-pagefooter", "baidu-tongji", "anchor-navigation-ex" ], "pluginsConfig": { "github-buttons": { "buttons": [ { "user": "biaochenxuying", "repo": "blog", "type": "star", "count": true, "size": "small" }, { "user": "biaochenxuying", "width": "160", "type": "follow", "count": true, "size": "small" } ] }, "donate": { "button": "打赏", "wechatText": "微信打赏", "wechat": "https://camo.githubusercontent.com/ee094d402f957e5d656a399b9dc50ff8c010114e/68747470733a2f2f75706c6f61642d696d616765732e6a69616e7368752e696f2f75706c6f61645f696d616765732f31323839303831392d666661623762643234643038633030642e6a7065673f696d6167654d6f6772322f6175746f2d6f7269656e742f7374726970253743696d61676556696577322f322f772f31323430" }, "tbfed-pagefooter": { "copyright":"Copyright © biaochenxuying.cn 2019", "modify_label": "该文件修订时间:", "modify_format": "YYYY-MM-DD HH:mm:ss" }, "baidu-tongji": { "token": "XXXXX" }, "anchor-navigation-ex": { "showLevel": false } } }
2.3 插件
插件的配置可以说是 GitBook 的核心。
详情可以看 GitBook - 快速打造可留言的博客,这里就不展开讲了。
3. VuePress VS GitBook
相同点
- 目前只支持
markdown
格式,图片、视频 等静态资源可以保存在本地,或者保存到允许访问的第三方服务商(如七牛云);
- 如果是
world
文档或者html
格式,要转换成md
格式才行。
- 找了几个
world
文档转换成 md 格式的工具,都不好用,特别是有原文档有图片的时候。
不同点
GitBook
的配置成本很小,可以本地编辑,然后直接部署;GitBook
官方还有个在线编辑器,不过内容要存在GitBook
的服务器上。
VuePress
的配置成本稍稍大一点,不过可以使用Vue
的语法与组件,定制化更自由一点,而且VuePress
中编写Vue
和平时一样,学习成本几乎为零,可以本地用 VsCode 编辑,然后直接命令行部署。
结论
- 都要用
markdown
语法来写文章,markdown
也就几个常用语法而已,非常简单上手。
- 非技术人员推荐用
GitBook
,技术人员推荐用VuePress
,特别是前端技术人员。
- 个人更喜欢
VuePress
。
4. 项目源码
本文中使用 VuePress
和 GitBook
的搭建的完整示例代码都已经上传到 GitHub
上了,可以自行下载来用。
只要把其中的一些配置信息换成自己的就行,比如 仓库
、Client ID
&& Client Secret
、作者等。
源码地址: https://github.com/biaochenxuying/blog 。
其中 VuePress
和 GitBook
的示例代码都在 blog-gitbook
和 blog-vuepress
里面了。