• 內容參照(Content References)
    • 嵌入本地檔案
    • 從其他書籍嵌入內容
    • 繼承

    內容參照(Content References)

    內容參照(Content referencing - conref),是從其他檔案或書籍中,重複取用內容的一種便利機制。

    嵌入本地檔案

    使用 include 標籤就能非常方便的載入其他檔案的內容:

    1. {% include "./test.md" %}

    從其他書籍嵌入內容

    GitBook 也能理解你嵌入的 git 路徑:

    1. {% include "git+https://github.com/GitbookIO/documentation.git/README.md#0.0.1" %}

    Git 網址的格式是這樣:

    1. git+https://user@hostname/project/blah.git/file#commit-ish

    Git 倉儲的結尾應該是 .git,接著則是要載入的檔案名稱。

    最後以 # 附加的可以是任何標籤、sha 或是倉儲分支,有點像是使用 git checkout 命令指定要從哪裡取出資料。預設值是 master

    繼承

    模板繼承,是讓你能重複使用模板的一種方式。撰寫模板時,你可以定義一些區塊(blocks),而這些區塊是使用子模板載入內容的。這樣的繼承鏈結並沒有層級數量的限制。

    簡單的說,就是你可以「在模板中使用不限數量、層級的子模板」。舉例來說,你有一個小模板用來呈現特殊的「名詞解釋」或「引用來源」,在不同章節中你都可以叫用這個小模板,但呈現不同的名詞、網站資料或是維基百科詞條。當你修改了這個小模板,所有使用到它的章節,都會自動套用新的呈現。

    區塊(block)定義了模板中的一個區段,賦予它一個特定的名稱。你在基礎模板中定義這些區塊,子模板則負責取得不同的內容,最後覆蓋、填充進這些區塊的位置。

    1. {% extends "./mypage.md" %}
    2. {% block pageContent %}
    3. # This is my page content
    4. {% endblock %}

    mypage.md 檔案裏,你就可以指定區塊該如何被替代:

    1. {% block pageContent %}
    2. 這裏擺放預設內容
    3. {% endblock %}
    4. # License
    5. {% import "./LICENSE" %}