- GitBook 是什么
- GitBook 能做些什么
- Ubuntu 下 gitbook 的安装
- 用 gitbook 来写书
- gitbook 的命令小结
- 自定义书本的 css
- 用插件来丰富你的书
- GitBook 相关链接
GitBook 是什么
GitBook 是一个可以用来构建一本漂亮的电子书的命令行工具1 , 基于 Node.js
可以使用 Markdown 文法来写作
只要你部署好一定的目录结构并且完成书的内容,就能通过命令很方便地转化成网页和其它格式的电子书
所以,用起来很简单
GitBook 能做些什么
写一本书,听起来有点太高级,但是往往却是如此现实
因此,你可以用 GitBook 来写一本属于你自己的书
至于书的内容,就由你自己来定:
- 可以是你幻想已久的一个世界
- 可以是平时生活中的小常识
- 可以是一本菜谱
- 可以是你整理知识的小册子
- 可以是…
Ubuntu 下 gitbook 的安装
-
安装 nodejs并建立软链接2
$ sudo apt-get install nodejs -y && sudo ln -s `which nodejs` /usr/bin/node
-
安装 NPM3
$ sudo apt-get install npm
-
安装 gitbook(全局)
$ sudo npm install gitbook-cli -g
用 gitbook 来写书
-
新建一个项目,命名为 learn-gitbook, 并初始化
$ mkdir learn-gitbook && cd learn-gitbook learn-gitbook $ gitbook init
learn-gitbook 下会生成两个文件 README.md 和 SUMMARY.md
-
构建并运行服务器
$ gitbook serve ./learn-gitbook --port 4001 ... Starting server ... Serving book on http://localhost:4001 ...
在浏览器中访问
http://localhost:4001
, 就可以看到一个没有内容的书 -
修改书籍名称
learn-gitbook $ echo "#learn gitbook" > README.md
在浏览器中查看浏览器标签页显示内容的变化
-
修改书籍介绍的内容
learn-gitbook $ echo "GitBook is a command line tool (and Node.js library) for building beautiful books using GitHub/Git and Markdown (or AsciiDoc)." >> README.md
在浏览器中查看 Introduction 页面的变化
-
增加几个章节(Markdown 的列表和链接语法)
在 SUMMARY.md 中增加以下内容 :* [Part I](part1/README.md) * [Writing is nice](part1/writing.md) * [GitBook is nice](part1/gitbook.md) * [Part II](part2/README.md) * [We love feedback](part2/feedback_please.md) * [Better tools for authors](part2/better_tools.md)
重建项目页面和目录 :
learn-gitbook $ gitbook init
在浏览器中查看左边侧边栏的变化:发现有了几个新的章节
-
为每个页面增加内容
你只要在相应的页面用 Markdown 文法写作
-
增加术语页面(GLOSSARY.md)
learn-gitbook $ touch GLOSSARY.md && vim GLOSSARY.md # 术语 这个术语的定义 # 另外一个术语 它的定义可以包含粗体和其他所有类型的内嵌式标记...
浏览器中你会发现 : 书中有
术语
、另外一个术语
字样的都被高亮,而且可以点击看到它的解释 -
在 book.json 中指定 gitbook 版本
列出已经安装的版本learn-gitbook $ gitbook versions Versions Installed: 2.2.0
新建 book.json,并指定版本 :
learn-gitbook $ touch book.json && vim book.json { "gitbook" : "2.2.0" }
避免运行 gitbook 时输出警告 :
warn: you should specify a gitbook version to use in your book.json, for example: 2.x.x
-
指定书籍所用语言风格
修改 book.json 内容为 :{ "gitbook" : "2.2.0", "language" : "cn" }
在浏览器中可以看到侧边栏的
Introduction
变为介绍
-
为侧边栏顶部增加链接
修改 book.json 内容为 :{ "gitbook" : "2.2.0", "language" : "cn", "links" : { "sidebar" : { "倘若微小" : "http://www.ifmicro.com/" } } }
在浏览器中可以看到侧边栏顶部增加一个链接,名为 倘若微小
-
最后,尽情写下你奇妙的想法,分享给大家吧
- 通过网站分享:把 learn-gitbook/_book 的内容放到一个云服务器上
- 发布电子书到云盘: 生成 pdf、epub、mobi电子书,放到云盘进行分享
gitbook 的命令小结
构建和运行
-
初始化项目目录:
$ gitbook init
会自动生成 SUMMARY.md 中指定的页面目录和页面
-
生成网站
$ gitbook build book_path output_path
-
构建网页并运行一个小型服务器
$ gitbook serve --port 4001 ... Serving book on http://localhost:4001
在浏览器上,访问 http://localhost:4001 , 就可以看到你的书
生成电子书(PDF、ePub和Mobi)
第一步 : 安装 calibre
第二步 : 执行对应命令
$ gitbook pdf book_path output_path/book_name.pdf
$ gitbook epub book_path output_path/book_name.epub
$ gitbook mobi book_path output_path/book_name.mobi
指定一个版本
$ gitbook build book_path --gitbook=2.3.0
$ gitbook help --gitbook=2.3.0
管理版本
-
查看 gitbook 使用
$ gitbook -h
-
查看可以获得的所有 GitBook 版本:
$ gitbook versions:available
-
安装最新的 GitBook 版本
$ sudo gitbook versions:install latest
自定义书本的 css
一般在生成站点时,会有默认的 css (_book/gitbook/style.css)
你也可以自定义 css,使你的书籍更好看
-
建立 css 文件
learn-gitbook $ mkdir -p assets/css && cd assets/css && touch myWebStyle.css myPdfStyle.css myMobiStyle.css myEpubStyle.css
在 myStyle.css 写下你的样式
-
在 book.json 中添加
{ "styles" : { "website" : "assets/css/myWebStyle.css", "pdf" : "assets/css/myPdfStyle.css", "mobi" : "assets/css/myMobiStyle.css", "epub" : "assets/css/myEpubStyle.css" } }
我分别为 site, pdf, mobi, epub 指定了 css, 那么分别生成它们的时候,会在默认的 css 基础上层叠指定的 css
用插件来丰富你的书
gitbook 文档推荐插件(主题也是插件的一种)的命名方式:
- gitbook-plugin-X
- gitbook-theme-X
发现插件
-
https://www.npmjs.com/search?q=gitbook-plugin
-
https://www.npmjs.com/search?q=gitbook-theme
-
http://plugins.gitbook.com/
安装插件
一旦你发现你需要的插件,在 book.json 添加:
{
"plugins": ["myPlugin", "anotherPlugin"]
}
对于 gitbook-plugin-X 的插件,请这样安装 :
book-dir $ gitbook install 或者 npm install gitbook-plugin-X
对于 gitbook-theme-X 的插件,请这样安装 :
book-dir $ npm install gitbook-theme-X && mv node_modules/gitbook-theme-X node_modules/gitbook-plugin-X`
PS : 具体插件请参照具体插件的文档
一些插件
disqus 评论系统 – disqus
-
安装 gitbook-plugin-disqus
sudo npm install gitbook-plugin-disqus -g
-
在 book.json 中添加 :
{ "plugins": ["disqus"], "pluginsConfig": { "disqus": { "shortName": "XXXXXXX" } } }
shortName
是你在 disqus.com 上创建 website 指定的 shortname
自动化封面 – autocover
- 安装 node-canvas
-
安装 gitbook-plugin-autocover
sudo npm install gitbook-plugin-autocover
-
在 book.json 中添加 :
{ "plugins": ["autocover"], "pluginsConfig": { "autocover": { "title": "My Book", "author": "Author", "font": { "size": null, "family": "Impact", "color": "#FFF" }, "size": { "w": 1800, "h": 2360 }, "background": { "color": "#09F" } } } }
GitBook 相关链接
-
GitBook 官方文档 : https://www.gitbook.com/book/gitbookio/documentation/details
-
GitBook 项目目录 : https://github.com/GitbookIO/gitbook
-
gitbook-cli 项目目录 : https://github.com/GitbookIO/gitbook-cli
-
GitBook API Documentation : http://developer.gitbook.com/
-
GitBook Enterprise Guide : https://www.gitbook.com/book/gitbookio/enterprise-guide/details
-
还有一个与之同名的在线创建和托管书籍的平台www.gitbook.com ↩
-
采用软链接解决ubuntu下 nodejs 命令名与 gitbook 内部使用 nodejs 命令名不一致
具体看nodejs vs node on ubuntu 12.04 ↩ -
Node Package Manager , 一个 nodejs 包管理和分发工具
NPM Github项目地址 ↩
- 上一篇: 用 tmux 保存工作现场
- 下一篇: 使用 SSH 登录服务器