怎麼用Markdown在github上寫書，並用pages展現

怎麼用git寫書

安裝環境

第一步 安裝node npm

先檢測本身電腦是否安裝了node npm

# 查看 node 版本
    node -v
     
    # 查看 npm 版本
    npm -v
    複製代碼

若是成功打印出版本號，說明你本地具有了 node 的運行環境（安裝 node 默認安裝 npm），而若是沒有或報錯，則你須要去 node 官網進行 node 的下載及安裝，如圖：

左邊的版本是推薦安裝的穩定版本，也就是目前已經被正式列入標準的版本，而右邊的版本是當前最新的版本，該版本包含了一些新的特性，還未被徹底列入標準，可能之後會有所變更。這裏建議你們安裝最新的 node 穩定版進行開發。

第二步 全局安裝 gitbook-cli

建議使用 npm 淘寶源：

npm config set registry https://registry.npm.taobao.org/

而後安裝gitbook -cli

npm i -g gitbook-cli

第三部 初始化電子書

# 建立一個目錄，進入
mkdir gitbook-demo
cd gitbook-demo
 
# 初始化電子書目錄
gitbook init 
 
# 編譯電子書
gitbook serve 
複製代碼

說明一下：

init 之後，目錄裏會有這兩個文件 README.md 和 SUMMARY.md，README.md 是對電子書的簡單介紹，SUMMARY.md 是電子書的目錄結構。

目錄結構長這樣：

* [電子書名稱](README.md)
* [第一章](chapter1/README.md)
    * [xxxx](chapter1/section1.1.md)
    * [xxxx](chapter1/section1.2.md)
* [第二章](chapter2/README.md)
    * [xxxx](chapter2/section2.1.md)
    * [xxxx](chapter2/section2.2.md)
複製代碼

編寫 SUMMARY.md，執行 gitbook init 生成目錄結構文件，而後編寫各個文件夾中生成的文件。

最後 gitbook serve。

gitbook serve 命令實際上會首先調用 gitbook build 編譯書籍，完成之後會打開一個 web 服務器，監聽在本地的 4000 端口。

若是當前書籍寫完了，想要發佈到本身的網站的話，也可使用命令輸出成html文件使用

gitbook build [書籍路徑] [輸出路徑]

最後搭配git一塊兒使用時，只須要在書籍根目錄下執行
git init
建立一個git倉庫，而後就愉快的拉取-書寫-提交循環便可了。

別忘了在提交的時候忽略掉module文件夾，否則每次提交拉取的時候會很痛苦....

圖形化編輯管理工具

用一個圖形化編輯管理工具，方便咱們實時編輯查看內容，這裏推薦用VScode，又能夠編輯Markdown，又能夠用git，又能夠分屏看效果。別忘了在提交的時候忽略掉module文件夾，否則每次提交拉取的時候會很痛苦....
處理VScode中md文件的亂碼問題，能夠手動生成md文件。不用系統自動生成，這樣能夠避免亂碼

gitbook目錄摺疊

插件名稱：toggle-chapters
效果：默認只在目錄導航中顯示章的標題，而不會顯示小節的標題，點擊每一章或者每一節會顯示當前章或節的子目錄，若是有的話，可是同時會收起其它以前展開的章節。
關於更多的gitbook插件，讀者能夠參考插件網站。
在根目錄(即與SUMMARY.md同級的目錄)下的配置文件 book.json(若是沒有則新建)中添加插件配置，如圖

配置完成後，可按照一下步驟進行：

$ cd gitbook根目錄
$ npm install gitbook-plugin-toggle-chapters (此時gitbook的根目錄下的node_modules文件夾中已經有了該插件了)
$ gitbook build
$ gitbook serve
訪問 http://localhost:4000 看你的插件是否已經生效。

圖片使用

能夠用博客園的此編輯器，添加圖片後發佈出來，而後再編輯的時候，就能夠看到圖片的連接，直接複製到本地編輯器就能夠

GitBook源文件發佈到gh-pages

複製_book文件下的全部文件，切換到 gh-pages分支，而後將本地編譯好的電子書文件（項目根目錄下的 _book 目錄裏的文件 ）上傳到這個分支目錄下，而後推送、推送玩要編輯仍是要回到master分支

你能夠將電子書提交到 github，在託管電子書的倉庫建一個 gh-pages 分支，將本地編譯好的電子書文件（項目根目錄下的 _book 目錄裏的文件 ）上傳到這個分支，而後就可使用這個網址訪問 https://liyao0312.github.io/StudyNotes/

固然也能夠發佈到gitbook，然而這個網站訪問有點慢-.-

git checkout --orphan gh-pages
//清空一下分支
rm -rf *
//而後將master分支下的_book靜態頁面文件內容所有複製到gh-pages分支下
git checkout master -- _book
//將_book中的子文件所有移到外層，並刪除_book
mv _book/* ./
rm -rf _book
//這時候gh-pages分支下就是所有的靜態頁面文件了，接下來就是提交到遠程gh-pages分支
git add .
git commit -m 'publish gh-pages'
git push origin gh-pages

GitBook - 安裝插件 - 內容摺疊功能 - 解決代碼過長，影響閱讀問題

在 book.json 中 增長下列字段

{
  "plugins": ["accordion"]
}

而後安裝

gitbook install

示例模板：

%accordion%Some title here%accordion%

Any content here

%/accordion%

啓動gitbook serve預覽以下：
![](https://img2018.cnblogs.com/blog/1237308/201908/1237308-20190811222516278-1451482174.png)

Markdown實用語法之實現頁面內跳轉

1
注意要點:

1. []中括號填寫須要在頁面上顯示的內容；
2. ()小括號內部聲明跳轉目標標題，以#開頭，標題題號若是包含.、下劃線直接忽略掉，標題文本中若是有空格，使用-橫槓符號替代，標題文本中的大寫字母轉換成小寫。

小技巧：
對於()小括號內的跳轉目標標題，能夠將Markdown導出HTML文件，查看HTML源碼，用對應標題 標籤下的id屬性值，這樣能夠保證正確跳轉。