GitBook 是什么

GitBook 是一个可以用来构建一本漂亮的电子书的命令行工具1 , 基于 Node.js

可以使用 Markdown 文法来写作

只要你部署好一定的目录结构并且完成书的内容,就能通过命令很方便地转化成网页和其它格式的电子书

所以,用起来很简单

GitBook 能做些什么

写一本书,听起来有点太高级,但是往往却是如此现实
因此,你可以用 GitBook 来写一本属于你自己的书

至于书的内容,就由你自己来定:

  • 可以是你幻想已久的一个世界
  • 可以是平时生活中的小常识
  • 可以是一本菜谱
  • 可以是你整理知识的小册子
  • 可以是…

Ubuntu 下 gitbook 的安装

  1. 安装 nodejs并建立软链接2

     $ sudo apt-get install nodejs -y && sudo ln -s `which nodejs` /usr/bin/node
    
  2. 安装 NPM3

     $ sudo apt-get install npm
    
  3. 安装 gitbook(全局)

     $ sudo npm install gitbook-cli -g
    

用 gitbook 来写书

  1. 新建一个项目,命名为 learn-gitbook, 并初始化

     $ mkdir learn-gitbook && cd learn-gitbook
     learn-gitbook $ gitbook init 
    

    learn-gitbook 下会生成两个文件 README.md 和 SUMMARY.md

  2. 构建并运行服务器

     $ gitbook serve ./learn-gitbook  --port 4001
     ...
     Starting server ...
     Serving book on http://localhost:4001
     ...
    

    在浏览器中访问 http://localhost:4001, 就可以看到一个没有内容的书

  3. 修改书籍名称

     learn-gitbook $ echo "#learn gitbook" > README.md
    

    在浏览器中查看浏览器标签页显示内容的变化

  4. 修改书籍介绍的内容

     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 页面的变化

  5. 增加几个章节(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		
    

    在浏览器中查看左边侧边栏的变化:发现有了几个新的章节

  6. 为每个页面增加内容

    你只要在相应的页面用 Markdown 文法写作

  7. 增加术语页面(GLOSSARY.md)

     learn-gitbook $ touch GLOSSARY.md && vim GLOSSARY.md		
     # 术语
     这个术语的定义
    
     # 另外一个术语
     它的定义可以包含粗体和其他所有类型的内嵌式标记...
    

    浏览器中你会发现 : 书中有 术语另外一个术语 字样的都被高亮,而且可以点击看到它的解释

  8. 在 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

  9. 指定书籍所用语言风格
    修改 book.json 内容为 :

     {
         "gitbook" : "2.2.0",
         "language" : "cn"
     }
    

    在浏览器中可以看到侧边栏的 Introduction 变为 介绍

  10. 为侧边栏顶部增加链接
    修改 book.json 内容为 :

    {
        "gitbook" : "2.2.0",
        "language" : "cn",
        "links" : {
            "sidebar" : {
                "倘若微小" : "http://www.ifmicro.com/"
            }
        }
    }
    

    在浏览器中可以看到侧边栏顶部增加一个链接,名为 倘若微小

  11. 最后,尽情写下你奇妙的想法,分享给大家吧

  • 通过网站分享:把 learn-gitbook/_book 的内容放到一个云服务器上
  • 发布电子书到云盘: 生成 pdf、epub、mobi电子书,放到云盘进行分享

gitbook 的命令小结

构建和运行

  1. 初始化项目目录:

     $ gitbook init
    

    会自动生成 SUMMARY.md 中指定的页面目录和页面

  2. 生成网站

     $ gitbook build book_path output_path
    
  3. 构建网页并运行一个小型服务器

     $ 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

管理版本

  1. 查看 gitbook 使用

     $ gitbook -h
    
  2. 查看可以获得的所有 GitBook 版本:

     $ gitbook versions:available  
    
  3. 安装最新的 GitBook 版本

     $ sudo gitbook versions:install latest
    

自定义书本的 css

一般在生成站点时,会有默认的 css (_book/gitbook/style.css)

你也可以自定义 css,使你的书籍更好看

  1. 建立 css 文件

     learn-gitbook $ mkdir -p assets/css && cd assets/css && touch myWebStyle.css myPdfStyle.css myMobiStyle.css myEpubStyle.css
    

    在 myStyle.css 写下你的样式

  2. 在 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

发现插件

  1. NPM-Search-gitbook-plugin

     https://www.npmjs.com/search?q=gitbook-plugin
    
  2. NPM-Search-gitbook-theme

     https://www.npmjs.com/search?q=gitbook-theme
    
  3. gitbook 插件官方地址

     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

  1. 安装 gitbook-plugin-disqus

     sudo npm install gitbook-plugin-disqus -g
    
  2. 在 book.json 中添加 :

     {
         "plugins": ["disqus"],
         "pluginsConfig": {
             "disqus": {
                     "shortName": "XXXXXXX"
                 }
             }  
     }
    

shortName 是你在 disqus.com 上创建 website 指定的 shortname

自动化封面 – autocover

  1. 安装 node-canvas
  2. 安装 gitbook-plugin-autocover

     sudo npm install gitbook-plugin-autocover
    
  3. 在 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 相关链接


  1. 还有一个与之同名的在线创建和托管书籍的平台www.gitbook.com 

  2. 采用软链接解决ubuntu下 nodejs 命令名与 gitbook 内部使用 nodejs 命令名不一致
    具体看nodejs vs node on ubuntu 12.04 

  3. Node Package Manager , 一个 nodejs 包管理和分发工具
    NPM Github项目地址 



blog comments powered by Disqus