超實(shí)用gitbook教程 - 快速搭建說明文檔

??gitbook 是一個基于 Node.js 的命令行工具，支持 Markdown 和 AsciiDoc 兩種語法格式，可以輸出 HTML、PDF、eBook 等格式的電子書。
??gitbook 與 Markdown 和 Git 息息相關(guān)，只有將它們結(jié)合起來使用，才能將它們的威力發(fā)揮到極致！通常我們會選擇合適的 Markdown 編輯工具以獲得飛一般的寫作體驗(yàn)；使用 GitBook 管理文檔，預(yù)覽、制作電子書；同時(shí)通過 Git 管理書籍內(nèi)容的變更，并將其托管到云端（比如 GitHub、GitLab、碼云，或者是自己搭建的 Git 服務(wù)器），實(shí)現(xiàn)多人協(xié)作。
??相比于word，因?yàn)樗远M(jìn)制格式保存、軟件不兼容、格式不兼容、難以進(jìn)行版本控制、難以實(shí)時(shí)分享預(yù)覽、難以多人協(xié)作等短板。而這恰恰是 GitBook + Markdown + Git 的長處。

安裝

1、使用npm全局安裝gitbook-cli

npm install gitbook-cli -g

2、使用gitbook --version來查看gitbook的版本

gitbook --version

3、新建一個文件夾，初始化gitbook，會自動生成兩個文件。
README.md —— 書籍的介紹寫在這個文件里
SUMMARY.md —— 書籍的目錄結(jié)構(gòu)在這里配置

gitbook init

4、接著，使用gitbook serve命令來啟動gitbook本地服務(wù)器，預(yù)覽書籍內(nèi)容。

gitbook serve

serve 命令也可以指定端口：

gitbook serve --port 2333

5、打開localhost:4000，會出現(xiàn)如下頁面



6、生成靜態(tài)網(wǎng)頁
執(zhí)行 gitbook build 命令構(gòu)建書籍，默認(rèn)將生成的靜態(tài)網(wǎng)站輸出到 _book 目錄。實(shí)際上，這一步也包含在 gitbook serve 里面，因?yàn)樗鼈兪?HTML，所以 gitbook 通過 Node.js 提供服務(wù)了。

gitbook build #生成靜態(tài)網(wǎng)頁

可以生成 PDF 格式的電子書：

gitbook pdf ./ ./mybook.pdf

生成 epub 格式的電子書：

gitbook epub ./ ./mybook.epub

生成 mobi 格式的電子書：

gitbook mobi ./ ./mybook.mobi

如果生成不了，還需要安裝工具ebook-convert，安裝好后，還需要執(zhí)行以下命令

ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin

編輯 SUMMARY.md 文件，內(nèi)容修改為：

* [快速入門](README.md)

* 業(yè)務(wù)組件
  * [日歷組件](component/rx-touch-calendar/README.md)
  * [展示瑞信頭像組件](component/rx-getPhoto-list/README.md)

目錄結(jié)構(gòu)

.
├── README.md
├── SUMMARY.md
├── book.json
├── component
│   ├── rx-getPhoto-list
│   └── rx-touch-calendar
└── style.css

book.json，該文件用于存放配置信息。

【title】書本的標(biāo)題
【author】作者的相關(guān)信息
【description】本書的簡單描述
【language】gitbook使用的語言
【root】指定存放 GitBook 文件（除了 book.json）的根目錄
【structure】指定自述文件，摘要，詞匯表等的路徑

gitbook支持許多插件，可以擴(kuò)展gitbook的功能。

【打賞功能：donate】

{
    "plugins": ["donate"],
    "pluginsConfig": {
        "donate": {
          "wechat": "例：/images/qr.png",
          "alipay": "http://blog.willin.wang/static/images/qr.png",
          "title": "默認(rèn)空",
          "button": "默認(rèn)值：Donate",
          "alipayText": "默認(rèn)值：支付寶捐贈",
          "wechatText": "默認(rèn)值：微信捐贈"
        }
    }
}

【廣告功能：ad】

{
  "plugins": ["ad"],
  "pluginsConfig": {
    "ad": {
      "contentTop": "<div>Ads at the top of the page</div>",
      "contentBottom": "%3Cdiv%3EAds%20at%20the%20bottom%20of%20the%20page%3C/div%3E"
    }
  }
}

// note: contentBottom is escape('<div>Ads at the bottom of the page</div>')

【目錄寬度可調(diào)節(jié)：splitter】

{
    "plugins": ["splitter"]
}

【github圖標(biāo)】

{
    "plugins": [ "github" ],
    "pluginsConfig": {
        "github": {
            "url": "https://github.com/your/repo"
        }
    }
}

【自定義頁腳：tbfed-pagefooter】

{
    "plugins": [ "tbfed-pagefooter" ],
    "pluginsConfig": {
        "tbfed-pagefooter": {
             "copyright":"&copy Taobao FED Team",
             "modify_label": "該文件修訂時(shí)間：",
             "modify_format": "YYYY-MM-DD HH:mm:ss"
        }
    }
}

【目錄章節(jié)可折疊：expandable-chapters】

{
    {
        plugins: ["expandable-chapters"]
    }
    {
        "pluginsConfig": {
            "expandable-chapters":{}
        }
    }
}

【暢言評論：changyan】

{
    "plugins": [
        "changyan"
    ],
    "pluginsConfig": {
        "changyan": {
            "appid": "your changyan's appid",
            "conf": "the conf in the code generate by changyan"
        }
    }
}

【返回頂部：back-to-top-button】

{
    "plugins" : [ "back-to-top-button" ]
}

??上面支持列舉了一些常用的插件，想要了解更多可以閱讀官方文檔，插件在book.json配置好后，需要安裝。

sudo gitbook install

book.json模板

{
  "title": "UI",
  "description": "UI組件庫",
  "author": "zhuyongbo",
  "language": "zh-hans",
  "links": {
    "sidebar": {
      "開放平臺": "http://e.cnpc.com.cn/opensdk/"
    }
  },
  "styles":{
    "website":"style.css"
  },
  "plugins": [
    "-lunr",
    "-search",
    "-livereload",
    "-sharing",
    "expandable-chapters",
    "search-plus",
    "splitter",
    "github",
    "-sharing",
    "emphasize",
    "include-codeblock",
    "tbfed-pagefooter",
    "back-to-top-button",
    "anchor-navigation-ex"
  ],
  "pluginsConfig": {
    "github": {
      "url": "https://github.com/webzhuyongbo"
    },
    "sharing": {
      "douban": false,
      "facebook": false,
      "google": false,
      "hatenaBookmark": false,
      "instapaper": false,
      "line": false,
      "linkedin": false,
      "messenger": false,
      "pocket": false,
      "qq": false,
      "qzone": false,
      "stumbleupon": false,
      "twitter": false,
      "viber": false,
      "vk": false,
      "weibo": false,
      "whatsapp": false,
      "all": [
        "weibo","qq","qzone","google","douban"
      ]
    },
    "anchor-navigation-ex": {
      "associatedWithSummary":false,
      "showLevel":true,
      "multipleH1": true,
      "mode": "float",

      "pageTop": {
        "showLevelIcon": false,
        "level1Icon": "fa fa-hand-o-right",
        "level2Icon": "fa fa-hand-o-right",
        "level3Icon": "fa fa-hand-o-right"
      }
    },
    "tbfed-pagefooter": {
      "copyright": "&copy;北京信息技術(shù)有限責(zé)任公司",
      "modify_label": "文檔更新時(shí)間：",
      "modify_format": "YYYY-MM-DD HH:mm:ss"
    }
  }
}

去掉gitbook的版權(quán)信息：

創(chuàng)建樣式表文件“styles/website.css”，添加代碼如下：

.gitbook-link {
    display: none !important;
}

編輯“book.json”文件，添加如下代碼：

{
    "styles": {
        "website": "styles/website.css"
    }
}

好了，讓我們看一下我們文檔的效果圖。


最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
【社區(qū)內(nèi)容提示】社區(qū)部分內(nèi)容疑似由AI輔助生成，瀏覽時(shí)請結(jié)合常識與多方信息審慎甄別。
平臺聲明：文章內(nèi)容（如有圖片或視頻亦包括在內(nèi)）由作者上傳并發(fā)布，文章內(nèi)容僅代表作者本人觀點(diǎn)，簡書系信息發(fā)布平臺，僅提供信息存儲服務(wù)。

相關(guān)閱讀更多精彩內(nèi)容

  • 概述 GitBook 是使用 GitHub / Git 和 Markdown（或AsciiDoc）構(gòu)建漂亮?xí)拿?..
    輝這樣說閱讀 3,122評論 0贊 4
  • 最近遇到一些問題，就是團(tuán)隊(duì)中會有些伙伴踩得坑的收集問題或者有些較為復(fù)雜的業(yè)務(wù)需求文檔共享上成本較高，所以考慮弄...
    tobAlier閱讀 4,046評論 0贊 5
  • 本文詳細(xì)講解了 Gitbook 生成電子書的完整過程，內(nèi)容包括：安裝、命令、配置、文檔結(jié)構(gòu)、生成電子書、部署。限于...
    靜默虛空閱讀 11,486評論 9贊 138
  • Gitbook是一個命令行工具，可以把你的Markdown文件匯集成電子書，并提供PDF等多種格式輸出。你可以把G...
    陳云峰閱讀 6,506評論 1贊 7
  • 一道道傷是 一串串想念的記號 記得那時(shí)年少 臉上淌著單純的笑 云也愛逍遙 在微風(fēng)里淺淺睡著 醒來后再也找尋不到 我...
    雷波恩閱讀 304評論 0贊 2

友情鏈接更多精彩內(nèi)容