如何在新版的gitbook上寫本身的書

前言

以前爲了學習QT當中的qmake，就去看QT的官方文檔，但QT的官方文檔都是英文的，而本身自己英文較差，就一咬牙決定不如就把qmake的使用文檔翻譯一下吧。這樣便可以加深對文檔的理解，也能夠留着本身之後查閱，順便也能夠將本身的文檔放在網上給想要的人進行查閱。因而就開始查找相關的工具，幾經展轉找到了gitbook這個網站。而後瞭解其使用方法，但不巧的是網站正處於改版時間，網上找到的教程基本全是針對舊版的，而新版的網站許多功能上尚未完善，這個折磨了我很久。

gitbook上提供了多種編輯文檔的方式，能夠在線編輯也能夠離線編輯後再上傳。新版的網站和舊版的網站已經有了好多的改變。具體的改變能夠參閱gitbook的網站文檔。其中的一種編輯文檔的方式就是將文檔像代碼同樣推送到GitHub,而後將文檔同步到gitbook。雖然以前我沒有用過git也沒有用過github，我仍是挺着迷這種編寫文檔的方式的，so。。。。由於新網站的功能還不算完善，因而各類折騰開始了。。。。之間我也聯繫了網站的管理員，他們也以郵件的方式回覆了我，表達了它們對網站功能不完善的歉意。這裏也表示感謝。。。。因而折騰了幾天仍是先將對gitbook網站的折騰先暫時擱置了。。。。

繼續查閱我還要哪些工具，因而我還要學習Markdown，git以及github的使用。因而學起來。。。。而關於文本編輯器的使用又陷入了糾結。。。再VScode和sublime之間徘徊，最後仍是發現vscode更適合我一些（這裏並非說sublime很差）。VScode中能夠很方便的預覽文檔，以及糾正語法錯誤。

教程

首先咱們須要再在github上建立一個倉儲，並在電腦的本地安裝git並將github上的倉儲同步到本地。新建github倉儲以及git的受用的方法能夠參閱廖雪峯的git教程。更詳細的也能夠閱讀git的官方教程。vscode和Markdown的使用本身百度就好啦。。。

作完上面的這些你就能夠在本地使用vscode編寫本身的文檔，並將文檔同步到github。下面介紹如何將文檔同步到gitbook上，並生成一本書。下面就開始吧。。。

對了這裏還要提一下，gitbook能夠添加一個.gitbook.ymal的文件文件的使用方法能夠查閱gitbook的網站文檔。

這裏咱們先建立一個gitbook帳號，這裏推薦直接使用本身的github帳號登錄gitbook。咱們按照gitbook的網站文檔中的步驟建立一個organization，而後再在organization下建立一個space。

而後按照網站文檔創建和GitHub上的倉儲進行關聯。

按照提示關聯本身所須要的倉儲就好。

寫在最後

gitbook官方文檔對.gitbook.yaml文檔的模板以下所示。該文件須要放在你GitHub倉儲的根目錄下，而後經過該文檔的設置，使用相對路徑指定gitbook下的根目錄。這裏給出我翻譯的書qmake-learn其倉儲位置是github qmake-learn

# Root directory to locate the content
# Default is the root directory of the repository.
root: ./

# Files to use as SUMMARY/README.
# (Relative to <root> directory)
structure:
  readme: README.md
  summary: SUMMARY.md

# Redirect urls to specific files (relative to the <root> directory)
redirects:
  previous/page: new-folder/page.md

這裏給出我翻譯的書qmake-learn其倉儲位置是github qmake-learn。其實gitbook中也提供了一些其餘的服務和設置。好比將你所寫的書的網址綁定到本身的域名當中。自定義書的logo，更改書的網址。具體的使用方法能夠看一下網站文檔，以及本身摸索一下。

這裏還要說一下，因爲gitbook是國外的網站要像流暢的在上面寫書，仍是要。。。。。不過瀏覽文檔沒什麼問題。