Build ebooks using Pandoc and Kindlegen
npm install buildebooksBuild Ebooks
============
> Mac 上需要預先準備好必要程式，參考 預裝程序。打開終端機在任何目錄輸入下列三條指令，都必須運作正常、顯示目前版本，否則製書程式無法執行成功。
``
$ npm -v //檢視 NPM 版本（2.8.4）。
$ pandoc -v //檢視 Pandoc 版本（1.13.2）。
$ kindlegen -releasenotes //檢視 Kindlegen 版本（V2.9）。
持續不穩定建置中。
`
$ npm install -g buildebooks
$ buildebooks -v //檢視目前版本
$ npm update -g //更新
1. npm install -g buildebooks 安裝於全域環境以便執行終端機指令模式。（如果遵照 預裝程序 的安裝方式，就不需要 sudo；萬一 Node.js 的安裝方式不同，可以嘗試使用 sudo npm install -g buildebooks 安裝。）buildebooks
2. 打開終端機，不管在單書目錄、多書目錄，或使用總專案管理目錄，都只需要輸入 命令就能自動判斷、製作電子書。
3. 未安裝在全域執行環境就無法使用終端機指令，你需要自行建立 Node 指令檔，例如：
`
var build = require('buildebooks').bes;
build();
4. 製書時輸入 node index.js 即可運作。
> 安裝於全域（with -g）之後，任意目錄執行 buildebook 或 buildebooks 均可。輸入 buildebook(s) -v 或 --version 會顯示目前版本。由於仍處於不穩定開發階段，常常運行 npm update -g 獲得最近的更新版本。
`
(1) Single Book Folder
/yourfolder
/book.md //製書索引，沒有這個檔案就不會製作電子書
/metadata.md //詮釋資料
/intro.md
/ch1.md
/ch2.md
/ch3.md
/Cover.png
/epub.css
/style/default.css
/image/cover.jpg
/part2/another.md
> 你可以自由使用次目錄擺放內容、素材，只要在製書索引中添加正確的路徑，例如 images/cover.jpg, style/stylesheet.css 或 part1/mycontent.md, part2/another.md 均可。
`
---唯一必要的設定
files:
- intro.md
- ch1.md
- ch2.md
- ch3.md自訂電子書檔名稱，未設定會使用上層目錄名稱（此例就是
）`filename: "mybook"
關閉製作。未設定時的預設值是 true
build: false
同步製作 Kindle 電子書，預設值是 false
kindle: true
編輯版本號
edit_version: "0.2"
是否複製成正式發行版本，預設是 false
public: false
發行版本號
release_verson: "1.0"
試讀版本（public 設為 true 時才會製作）
sample:
- intro.md
- ch1.md
---
> 0.2.x 之後，非單書目錄才會用到 config.md。
使用 config.md 設定：擺放書籍專案的目錄（base）、擺放電子書的目錄（dest）、書籍索引檔的名稱（index）以及預設讀取書籍資料的檔案名稱（metafile）。可以沒有這個檔案，系統就會依照預設值尋找。
`
---擺放所有書籍專案的目錄（使用集中目錄的情境）
base: 'projects'預設擺放製成書檔的目錄
dest: 'books'製書索引檔的名稱
index: 'book.md'預設尋找的詮釋資料檔名稱
metafile: 'metadata.md'共用樣式檔目錄
stylesFolder: 'styles'
---
- 你所有的書籍專案都在 projects 目錄下，一個專案一個子目錄，名稱不能重複。book.md
- 書籍專案內使用一個 作為製書指引（索引）檔。
- 書籍（詮釋）資料檔是必要的。
除了上面提到的「單書目錄」之外，以下兩種目錄也都可以自由使用：
`
(2) Multi-Books folder
/somefolder
/book1
/book2
/book3
/styles （可以使用共用樣式目錄）
config.md （可以使用設定檔， 設定在此狀況下無效）`
使用終端機在該目錄下執行 [ ~/somefolder] $ buildebooks 即可。
`
(3) Center Projects folder
/minifactory
/projects
/book1
/book2
/book3
/styles （共用樣式目錄）
config.md （可以使用設定檔）
使用終端機在該目錄下執行 [ ~/minifactory] $ buildebooks 即可。
> 安裝在全域的好處就是：你的書籍專案目錄不再有什麼 index.js 或是 node_modules 目錄之類的玩意，完全只有與內容相關的檔案，清爽許多。
某些製書程序要求使用固定的檔名與順序（例如 01-xxx, 02-xxx...），不太人性且增加了麻煩。Leanpub 與 GitBook 使用的模式好一些：透過一個索引檔案，告訴系統要使用哪些內容檔案製作電子書。
使用製書索引檔還有其他好處：
1. 書籍專案目錄下，可以自由擺放各種檔案，草稿、參考文件、編輯註記等等，無需受限任何規則。
2. 只有那些寫進索引檔的內容文件，才會影響電子書的製作。
3. 索引檔還可以處理一本書製作時的獨立配置，像是一些開關，要不要暫時關閉製書程序、要不要同步生成 Kindle 電子書、設定編輯版本等等。
製書索引檔至少需要指定內容檔案（files），依序構成書籍的內容（目錄）。
還可以配置下面這些開關：
- filename 未設定時，書籍專案目錄名稱就是書檔名稱。metafile
- 書籍詮釋資料檔是必要的，預設會尋找 metadata.md，你可以自由指定。build
- 設置為 true 或 false，未設定的預設值為 true，也就是在執行程序時會自動製作電子書，當你還在書寫或編輯流程，或是已經發行一個正式版本，暫時不需要每次都製作、覆蓋電子書檔時，可以選擇將其關閉。kindle
- 設置為 true/false，預設為 false。開啟這個開關會在製書時同步產生 Kindle 版本（使用 Kindlegen 轉製）。edit_version
- 編輯版本設定。stylesheet
- 使用的樣式檔，在此處設置的優先權比詮釋資料檔更高，在編輯、修正測試與改版的情境下比較方便。指定樣式檔時，專案目錄找不到，會去比對共用樣式目錄。cover-image
- 指定封面圖檔，在此處設置的優先權比詮釋資料檔更高，便利編輯與改版過程的使用。publish
- 設置為 true/false，是否產生正式發行書檔。（not yet）publish_version
- 設置發行版本號。（not yet）
當你持續書寫與編輯，並執行製書程序時���filename.epub 或 projectname.epub 會被擺在專案目錄下的 books 目錄，每次製書都會覆蓋掉舊檔。在測試與發想階段你可以這樣用，但隨著內容愈來愈多，或是已經有對外提供過書檔，你會希望能更清楚的管理流程，這時就需要設置「編輯版本號」。
試著將編輯版本號設置為 "0.1"，這時製成的書檔會變成 filename-0.1.epub。當版本號未異動，任何修改與重複製書都會覆蓋掉舊檔。一旦你將版本號升級成 "0.2" 時，一個新的 filename-0.2.epub 被製作出來，"0.1" 版的書檔依舊保留著。
使用概念很簡單，當書寫與編輯告一段落，特別是有將書檔交給其他人檢視，或是已經發行出去時，你應該保留這一版的書檔供參考比對，此時就只需要將「編輯版本號」往前推進一版即可。
使用樣式檔（stylesheet）時，最簡單的方法就是擺放在書籍專案目錄，指定目錄下的 epub.css 或次目錄中的 stylesheet/epub.css。因為詮釋資料是跟著書走的，理論上應該在其中設定要使用的樣式檔，這也是 Pandoc 的預設處理模式。
但你可以在製書索引檔中指定樣式檔，同樣是以一個專案的目錄為基準去優先比對檔案，找到了就使用，測試調整時比較方便。
因為這個系統一開始就以能「同時處理多本書」為出發點，共用樣式檔的可能性很高，所以在基本設定中加了一個 stylesFolder （共用樣式目錄）的選項，預設是 styles，可以擺放多個常用、通用的樣式。
如此一來，假設你預先製作好了 default.css、fiction.css 與 tech.css 幾種樣式，就可以在詮釋資料或製書索引中直接指定。若是書籍專案目錄下有同名的樣式檔，會優先被使用。
比對優先順序為：
1. 索引檔中指定了樣式，先找專案目錄，其次是共用樣式目錄，先找到先用。
2. 索引檔中未指定或找不到，詮釋資料有指定，一樣先找專案目錄，其次是共用樣式目錄，先找到先用。
3. 索引檔或詮釋資料檔中均未指定，或在專案目錄與共用樣式目錄都找不到，套用的就是 Pandoc 預設、最精簡的樣式。
Pandoc 可以接受這些唯一識別碼：ISBN-10, GTIN-13, UPC, ISMN-10, DOI, LCCN, GTIN-14, ISBN-13, Legal deposit number, URN, OCLC, ISMN-13, ISBN-A, JP, OLCC，這些也是 EPUB 允許的代碼。
在詮釋資料中以這樣的形式輸入：
`
identifier:
- scheme: ISBN-13
text: 978-986-276-419-0
如果沒有設定任何一個，Pandoc 預設會自動產生一個隨機生成的 UUID，每一次製作時都不一樣。對於自主出版或新型態的數位出版來說，沒有必要去申請傳統的 ISBN，所以要想辦法讓每一個書籍專案擁有一個不變的唯一識別 UUID，不管轉製多少次，這個識別碼都該維持不變。
所以當第一次轉製電子書時，在書籍專案目錄下會建立一個 uuid.xml 的檔案，~~另外在根目錄的 books.json 中也有一份~~（_0.2.0 之後已不再使用_）。~~這個檔案由程式管控，不應該碰觸。萬一 uuid.xml 被殺掉了，下次製書時會自動產生，UUID 依舊維持不變。但若是殺掉了 books.json，就請也一併手動移除 uuid.xml，否則 UUID 就會不一致了。~~ 書籍目錄下的 uuid.xml 若被人工移除，下次製書時會重新產生，但 UUID 不同，請小心。
> 目前這個維持「唯一識別 UUID」的機制還不是很牢靠，在專案目錄名稱不變的狀況下，一般不會出錯。未來或許該添加一些清理、檢測或搬移的功能。
在製書索引中增加了一個 sample 的設定，方法與 files 相同。這是準備與發行功能搭配的選項，因此 publish 也必須設置為 true。
簡單的說，就是製作一個「試讀版本」，可以自由指定要擺放的內容章節。檔名後以 -sample 區隔，命名原則與正式版（含版本號）一致，同時適用於 EPUB 與 Kindle 版本的製作（因此若指定 publish: true 且設置了 sample` 要使用的內容，一次就會產生四個書檔。
加入檢查系統是否已安裝 Pandoc 與 Kindlegen。
找不到 Pandoc 會提示並跳出；找不到 Kindlegen 則顯示警告訊息。