美文网首页资源精品生活百态
使用Gitbook写开源书籍,过一把作家瘾

使用Gitbook写开源书籍,过一把作家瘾

作者: 全科 | 来源:发表于2016-04-26 22:27 被阅读9355次
    • 转载请注明出处,谢谢

    初级(适合没有编程基础的童鞋看)

    使用GitBook Editor 写开源书籍

    这个是gitbook官方出的编辑器,使用简单

    首先下载GitBook Editor
    GitBook Editor

    下载地址:https://www.gitbook.com/editor

    支持Mac、Linux、Windows

    安装
    Windows
    • 下载gitbook-win.zip
    • 解压;
    • 打开GitBook.exe安装;
    Mac
    • 下载 gitbook-mac.dmg安装即可
    Linux
    • 下载 gitbook-linux32.tar.gz
    • 使用tar -xvzf gitbook-linux32.tar.gz解压
    • 运行脚本 cd GitBook && ./install.sh安装

    使用

    安装完成之后,如果有github账号直接,登录,但是用github登录之后也需要设置gitbook的邮箱和密码,等会儿要用到,没有账号的直接注册就好;

    登录后,可以直接在gitbook上创建书籍,建议在gitbook网站上创建书籍,然后通过GitBook Editor clone 下来;

    clone 下来之后 可以直接写书了,先在感觉是不是特别简单?别急,为了更爽的写作还需要继续看看下面。

    怎么和github同步?

    如果没有github账号,先注册,之后绑定github账号 https://www.gitbook.com/@quanke/settings#social(把连接中的quanke修改为自己的用户名)

    如果绑定了了github账号,需要设置权限,https://www.gitbook.com/@quanke/settings#github(把连接中的quanke修改为自己的用户名), Reconnect GitHub Account 选择 With access to public repositories

    当授权好了之后,我们来到书的设置( Settings )页面,点击设置github https://www.gitbook.com/book/quanke/vert-x-core-manual-for-java/settings/github(把quanke替换成你的用户名,把vert-x-core-manual-for-java替换成书名)

    如果原来这本书是github里写的,直接填入github的地址就好,如果账号都是新建的,什么都没有,那就点击Export to GitHub (注意填入gitbook的用户名密码不是github的)

    如果上面的步骤没问题,点击 Add webhook 就OK了,给github增加了一个钩子,也就是说当你的github更新的时候,会告诉gitbook

    还有一步很关键,在你的GitBook Editor中,打开我们刚才clone下来的书,点击菜单里的 Book -> Repository Settings ,把这个设置成为刚才导到github的地址,之后就可以在GitBook Editor写作了。。有什么不懂的,直接可以留言问我

    进阶(适合有编程基础的童鞋看)

    gitbook 安装

    1. 安装npm
      从网站 https://nodejs.org/#download 下载node.js源代码(点击绿色的INSTALL),
      解压
    ./configure
    make
    make install 
    

    成功执行后,npm就被安装好了。

    1. gitbook 安装
    npm install -g gitbook-cli
    
    gitbook -V 
    

    查看gitbook是否安装成功。

    gitbook 使用

    1. 根据目录生成图书结构
    1.1 README.md 与 SUMMARY编写
    

    README.md

    这个文件相当于一本Gitbook的简介。

    $ mkdir test_gitbook
    $ touch README.md
    

    SUMMARY.md

    这个文件是一本书的目录结构,使用Markdown语法,
    如我们这本书的SUMMARY.md:

    $ touch SUMMARY.md
    $ vim SUMMARY.md
    

    输入

    * [简介](README.md)
    * [第一章](chapter1/README.md)
     - [第一节](chapter1/section1.md)
     - [第二节](chapter1/section2.md)
    * [第二章](chapter2/README.md)
     - [第一节](chapter2/section1.md)
     - [第二节](chapter2/section2.md)
    * [结束](end/README.md)
    
    

    1.2 生成图书结构

    当这个目录文件创建好之后,我们可以使用Gitbook
    的命令行工具将这个目录结构生成相应的目录及文件:

    $ gitbook init
    $ tree . #查看建立的目录和文件
    
    .
    ├── chapter1
    │   ├── README.md
    │   ├── section1.md
    │   └── section2.md
    ├── chapter2
    │   ├── README.md
    │   ├── section1.md
    │   └── section2.md
    ├── end
    │   └── README.md
    ├── README.md
    └── SUMMARY.md
    

    我们可以看到,gitbook给我们生成了与SUMMARY.md所
    对应的目录及文件。

    每个目录中,都有一个README.md文件,相当于一章的说明。

    1. 生成图书

    2.1 输出为静态网站

    你有两种方式输出一个静态网站:

    2.1.1 本地预览时自动生成

    当你在自己的电脑上编辑好图书之后,你可以使用Gitbook
    的命令行进行本地预览:

    $ gitbook serve .
    

    然后浏览器中输入 http://localhost:4000 就可以预览生
    成的以网页形式组织的书籍。

    这里你会发现,你在你的图书项目的目录中多了一个名为
    _book的文件目录,而这个目录中的文件,即是生成的静态
    网站内容。

    使用build参数生成到指定目录
    与直接预览生成的静态网站文件不一样的是,使用这个命令,
    你可以将内容输入到你所想要的目录中去:

    $ mkdir /tmp/gitbook
    $ gitbook build --output=/tmp/gitbook
    

    2.2 输出PDF

    输入为PDF文件,需要先使用NPM安装上gitbook pdf:

    $ sudo npm install gitbook-pdf -g
    

    我在执行上面这条命令的时候出现了下面的错误:

    ***************************************************
    Downloading http://cdn.bitbucket.org/ariya/phantomjs/downloads/phantomjs-1.9.7-linux-i686.tar.bz2
    Saving to /usr/local/lib/node_modules/gitbook-pdf/node_modules/phantomjs/phantomjs/phantomjs-1.9.7-linux-i686.tar.bz2
    Error: connect ETIMEDOUT
        at exports._errnoException (util.js:746:11)
        at TCPConnectWrap.afterConnect [as oncomplete] (net.js:1010:19)
    npm ERR! Linux 3.2.0-4-686-pae
    npm ERR! argv "/usr/local/bin/node" "/usr/local/bin/npm" "install" "gitbook-pdf" "-g"
    npm ERR! node v0.12.7
    npm ERR! npm  v2.11.3
    npm ERR! code ELIFECYCLE
    
    
    npm ERR! phantomjs@1.9.7-5 install: `node install.js`
    npm ERR! Exit status 1
    npm ERR! 
    npm ERR! Failed at the phantomjs@1.9.7-5 install script 'node install.js'.
    npm ERR! This is most likely a problem with the phantomjs package,
    npm ERR! not with npm itself.
    npm ERR! Tell the author that this fails on your system:
    npm ERR!     node install.js
    npm ERR! You can get their info via:
    npm ERR!     npm owner ls phantomjs
    npm ERR! There is likely additional logging output above.
    
    
    npm ERR! Please include the following file with any support request:
    npm ERR!     /home/wangxq/repository/phantomjs/npm-debug.log
    
    
    ***************************************************
    
    

    由错误报告内容的第一行可以知道,发生错误的原因是下载
    phantomjs发生了错误,因此我们需要手动下载和安装。

    解决方法:[1]

    $ git clone git://github.com/ariya/phantomjs.git
    $ sudo apt-get install build-essential g++ flex bison gperf ruby perl \
      libsqlite3-dev libfontconfig1-dev libicu-dev libfreetype6 libssl-dev \
      libpng-dev libjpeg-dev python libx11-dev libxext-dev       #安装编译需要的工具和依赖
    $ cd phantomjs
    $ git checkout 1.9.7  #注意:这里的1.9.7是phantom的版本号,可以由错误报告的第一行找出 
    $ ./build.sh --jobs 4
    $ sudo cp bin/phantomjs /bin/
    $ sudo npm install gitbook-pdf -g  #重新进行安装
    
    

    然后,使用下面的命令,要PDF文件,首先安装依赖库:

    $ sudo apt-get install calibre  
    $ gitbook -v 2.1.0 pdf .
    

    发生错误:

    *****************************************************
    info: start conversion to pdf ....ERROR
    
    
    Error: Command failed: /bin/sh -c ebook-convert /tmp/tmp-29384ctltwbk/SUMMARY.html /tmp/tmp-29384ctltwbk/index.pdf --title="" --comments="这本书是gitbook的一个例子" --language="en" --book-producer="GitBook" --publisher="GitBook" --chapter="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter ')]" --chapter-mark="pagebreak" --page-breaks-before="/" --level1-toc="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter-1 ')]" --level2-toc="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter-2 ')]" --level3-toc="descendant-or-self::*[contains(concat(' ', normalize-space(@class), ' '), ' book-chapter-3 ')]" --no-chapters-in-toc --max-levels="1" --breadth-first --margin-left="62" --margin-right="62" --margin-top="56" --margin-bottom="56" --pdf-default-font-size="12" --pdf-mono-font-size="12" --paper-size="a4" --pdf-header-template="<p class='header'><span></span></p>" --pdf-footer-template="<p class='footer'><span>_SECTION_</span> <span style='float:right;'>_PAGENUM_</span></p>"
    Usage: ebook-convert input_file output_file [options]
    
    
    Convert an ebook from one format to another.
    
    
    input_file is the input and output_file is the output. Both must be specified as the first two arguments to the command.
    
    
    The output ebook format is guessed from the file extension of output_file. output_file can also be of the special format .EXT where EXT is the output file extension. In this case, the name of the output file is derived the name of the input file. Note that the filenames must not start with a hyphen. Finally, if output_file has no extension, then it is treated as a directory and an "open ebook" (OEB) consisting of HTML files is written to that directory. These files are the files that would normally have been passed to the output plugin.
    
    
    After specifying the input and output file you can customize the conversion by specifying various options. The available options depend on the input and output file types. To get help on them specify the input and output file and then use the -h option.
    
    
    For full documentation of the conversion system see
    http://manual.calibre-ebook.com/conversion.html
    
    
    Whenever you pass arguments to ebook-convert that have spaces in them, enclose the arguments in quotation marks.
    
    
    ebook-convert: error: no such option: --pdf-default-font-size
    
    
    *****************************************************
    
    

    解决方法[2]

    $ 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()"
    
    
    $ gitbook -v 2.1.0 pdf .  # 重新执行命令生成pdf,目标文件为book.pdf
    
    

    问题

    如果输入gitbook init命令,出现Installing version 2.1.0
    需要耐性等待安装。

    全科龙婷▼升职加薪

    image

    相关文章

      网友评论

      • f674382e9478:战略马
      • 乡村骑士:好文,mark
      • 813d428adff9:https://fantasyjxf.gitbooks.io/px4-wiki/content/
        我也做了一本GitBook 想问一下 怎么可以在里面加入一个“”回到顶部“”这样的插件啊
        6b2145523452:在book.json 里面 plugins filed添加你需要的插件
        然后gitbook install
      • 沈正方:不会是vim把?这个对输入文字不太友好,不太好用啊
      • 沈正方:今天弄了半天geitbook这个,gitbook editor和gitbook命令行的方式都弄好了,现在我有一个困惑1.gitbook editor不能生成网页预览,找不到gitbook editor编辑好的书籍源文件(.md文件),2.而gitbook命令行呢倒是有源文件,也能网页预览,但是没有gitbook editor这样的编辑器来写书
        想请问下楼主,这两个工具有办法结合使用吗?用gitbook命令行的情况下,你是用的什么编辑器编辑文件的啊??
        沈正方:mac呢
        全科:@BrianShen 你用的是windows 还是mac ?windows 去用户目录里去找
      • Gavin_peng:楼主你好,我安装过node.js之后,在终端执行这句话 npm install -g gitbook-cli 怎么一直报错呀?
        Gavin_peng:@quanke 好了 应该是权限不够 用了sudo安装就行了 多谢哈 :blush:
        Gavin_peng:@quanke 设置了淘宝的镜像,但是还是报错呢,错误如下:
        npm ERR! tar.unpack untar error /Users/iningfeng/.npm/gitbook-cli/2.3.0/package.tgz
        npm ERR! Darwin 15.5.0
        npm ERR! argv "/usr/local/bin/node" "/usr/local/bin/npm" "install" "-g" "gitbook-cli"
        npm ERR! node v4.4.5
        npm ERR! npm v2.15.5
        npm ERR! path /usr/local/lib/node_modules/gitbook-cli
        npm ERR! code EACCES
        npm ERR! errno -13
        npm ERR! syscall mkdir
        全科:@Gavin_peng 报什么错?如果没有权限加sudo

        如果没有科学上网需要科学上网或者设置国内镜像
      • 71739aed572c:很喜欢
        全科:@sebeeven :pray:
      • youngCode:不用命令行,怎么生成静态网站?
        youngCode:gitbook editor 初代,是可以直接生成静态网站预览。但现在的四代反而找不到那个预览生成在哪里了。
        全科:@youngCode 没有搞过,如果使用hexo比较简单,直接把md文件拿出来丢hexo里面生成就可以了
      • xingou:先收藏:smile:
      • 喵在野:赞,正打算用gitbook
        全科: @喵在野 有问题交流。。。
      • 靳小都:好东西,后面有时间,也自己写一本书
        全科:@靳小都 期待
      • 一俢:收

      本文标题:使用Gitbook写开源书籍,过一把作家瘾

      本文链接:https://www.haomeiwen.com/subject/ixqcrttx.html