Back

使用gitbook 来写作 - gitbook 命令行

发布时间: 2015-09-05 22:10:00

refer to:  https://github.com/GitbookIO/gitbook

 安装gitbook: 

$ npm install gitbook-cli -g

 启动命令是: 

 $ cd < your book folder>
 $ gitbook serve # 注意不是 server 

markdown 语法:   https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet#code

必须的文件

README.md : 对于书的介绍, 封面等. 会自动导入到最终的summary中

SUMMARY.md: 书的目录

安装: 

$ npm install gitbook-cli -g

下载某个gitbook repo后, 启动gitbook

$ gitbook init

根据以有的gitbook, 创建对应的html页面:

$ gitbook build

目前的特性:

生成html , pdf, epub, mobi 等格式, html格式的页面中还有搜索, 变换CSS等功能
支持多语言(i18n)
引用目录
封面
ASCII doc
变量和模板

生成电子书

(可以使用 --log debug 来显示详细信息. )

$ gitbook build

# 生成pdf之前,linux 先安装好这个: 
$ sudo -v && wget -nv -O- https://raw.githubusercontent.com/kovidgoyal/calibre/master/setup/linux-installer.py | sudo python -c "import sys; main=lambda:sys.stderr.write('Download failed\n'); exec(sys.stdin.read()); main()"
# 对于mac ,则要 （ 来下载calibre app http://calibre-ebook.com/download . 安装好之后，再建立软连接) :
$ sudo ln -s ~/Applications/calibre.app/Contents/MacOS/ebook-convert /usr/bin
You can replace /usr/bin with any directory that is in your $PATH. ）
$ gitbook pdf . my_book.pdf --log debug

$ gitbook epub . my_book.epub 
$ gitbook mobi . my_book.mobi
$ gitbook json  --format=json

必须的文件

README.md : 对于书的介绍, 封面等. 会自动导入到最终的summary中

SUMMARY.md: 书的目录

多语言支持(i18n)

1. 有个LANGS.md, 里面 指定了语言:

* [English](en)
* [Deutsch](de)
* [Español](es)
* [Français](fr)

2. 把 zh, en, es 等代表语言的文件夹放在根目录下, 下面 再存放对应的文件. 具体的例子见: https://github.com/progit/progit

术语列表

新建一个文件 GLOSSARY.md , 里面增加 几个术语:

# term
Definition for this term

# Another term
With it's definition,

然后, 书中所有的 "term", "Another term" 都会自动高亮显示. 并且书末还会自动生成一份"术语列表"

页面中使用变量 (templates and variables) 

可以在book.json中声明一个变量, 然后在页面中引用它:

// book.json: 
{
    "variables": {
        "this_year": "2015"
    }
}

// 在某个md 文件中引用, 前缀是 book: :
今年是: {{book.this_year}}

引用其他md文件的内容

{% include "./test.md" %}

{% include "git+https://github.com/GitbookIO/documentation.git/README.md#1.0.1" %}

{% include book.ref_doc_readme %}

忽略 一些文件

把需要忽略的文件,放到下面任意一个文件中即可, ( 格式同 .gitignore): .gitignore, .bookignore and .ignore

封面

两个文件: cover.jpg (1800 x 2360) , cover_small.jpg, 使用的plugin 是: https://github.com/GitbookIO/plugin-autocover

使用Plugin

Plugin 可以使gitbook的功能大大增强, 更多的plugin 见: http://plugins.gitbook.com

调试

$ gitbook build ./ --log=debug --debug

Back