自訂主題

變更主題以符合你的需求。

如果你想對現有主題做一些微調，你不用從頭開始建立自己的主題。對於僅需一些 CSS 和/或 JavaScript 的小調整，你可以 使用 docs_dir。然而，對於更複雜的自訂，包括覆寫範本，你將需要 使用主題 custom_dir 設定。

使用 docs_dir

你可以使用 extra_css 和 extra_javascript 設定選項微調和自訂現有主題。若要使用它，你僅需在 文件目錄 中包含 CSS 或 JavaScript 檔案。

舉例來說，若要變更文件標題顏色，建立一個名為（例如）style.css 檔案，並把它放在文件 Markdown 旁。在那個檔案中加入以下 CSS。

h1 {
  color: red;
}

然後你需要將它加到 mkdocs.yml

extra_css:
  - style.css

做完這些變更後，當你執行 mkdocs serve 時，它們將顯示出來 - 如果你已經執行，你應該會看到這些 CSS 變更被自動抓取，你的文件也會被更新。

注意

任何額外的 CSS 或 JavaScript 檔案將會在頁面內容後加入已產生的 HTML 文件中。如果你想包含一個 JavaScript 函式庫，你可能會比較希望透過使用主題 custom_dir 來包含那個函式庫。

使用主題 custom_dir

theme.custom_dir 設定選項可以指向一個包含覆寫上層主題檔案的檔案目錄。上層主題會是定義在 theme.name 設定選項中的主題。custom_dir 中的任何檔案，如果它的名稱與上層主題中的檔案同名，會取代上層主題中同名的檔案。custom_dir 中的任何額外檔案會新增到上層主題。custom_dir 的內容應該要對應上層主題的目錄結構。你可以包含主題中所包含的範本、JavaScript 檔案、CSS 檔案、圖片、字型或任何其他媒體。

注意

要讓這個功能運作，theme.name 設定必須設定到已安裝的主題。如果 name 設定為 null (或未定義)，表示沒有主題可覆寫，而 custom_dir 的內容就必須是一個完整且獨立的主題。請參閱 主題開發者指南 以取得更多資訊。

例如，mkdocs 主題 (瀏覽原始碼) 會包含以下目錄結構（部分）

- css\
- fonts\
- img\
  - favicon.ico
  - grid.png
- js\
- 404.html
- base.html
- content.html
- nav-sub.html
- nav.html
- toc.html

若要覆寫那個主題中包含的任何檔案，請在 docs_dir 旁邊建立一個新目錄

mkdir custom_theme

然後把您的 mkdocs.yml 設定檔案指向新目錄

theme:
  name: mkdocs
  custom_dir: custom_theme/

若要覆寫 404 錯誤頁面（「找不到檔案」），請在 custom_theme 目錄新增一個稱為 404.html 的新範本檔。如需關於可在範本中包含什麼內容的資訊，請檢閱 主題開發者指南。

若要覆寫 favicon，您可以在 custom_theme/img/favicon.ico 新增一個新圖示檔。

若要包含 JavaScript 程式庫，請將該程式庫複製到 custom_theme/js/ 目錄。

您的目錄結構現在應該會如下所示

- docs/
  - index.html
- custom_theme/
  - img/
    - favicon.ico
  - js/
    - somelib.js
  - 404.html
- config.yml

注意

包含在父主題中（定義於 name）但未包含在 custom_dir 中的任何檔案，仍會被使用。custom_dir 只會覆寫或取代父主題中的檔案。如果您想要移除檔案或從頭建立一個主題，則應該檢閱 主題開發者指南。

覆寫範本區塊

內建的主題會在範本區塊內實作其許多部分，而這些區塊可分別在 main.html 範本中覆寫。只要在 custom_dir 中建立一個 main.html 範本檔，並在那個檔案中定義替代區塊即可。只要確保 main.html 會延伸自 base.html。例如，若要變更 MkDocs 主題的標題，則您的替代 main.html 範本會包含下列內容

{% extends "base.html" %}

{% block htmltitle %}
<title>Custom title goes here</title>
{% endblock %}

在上面的範例中，在您的自訂 main.html 檔案中定義的 htmltitle 區塊會用來取代在父主題中定義的預設 htmltitle 區塊。只要這些區塊定義在父主題中，您可以重新定義任意多個區塊。例如，您可以將 Google Analytics 腳本替換為其他服務的腳本，或將搜尋功能替換為您自己的功能。您需要查閱準備使用的父主題才能確定哪些區塊可用於覆寫。MkDocs 和 ReadTheDocs 主題會提供下列區塊

  • site_meta：包含文件標頭中的 meta 標籤。
  • htmltitle：包含文件標頭中的頁面標題。
  • styles：包含用於樣式表的 link 標籤。
  • libs：包含頁面標頭中包含的 JavaScript 程式庫 (jQuery 等)。
  • scripts：包含應於頁面載入後執行的 JavaScript 腳本。
  • analytics：包含分析腳本。
  • extrahead：<head> 中的一個空區塊，用於插入自訂標籤、腳本等。
  • site_name：包含導覽列中的網站名稱。
  • site_nav：包含導覽列中的網站導覽功能。
  • search_button：包含導覽列中的搜尋方塊。
  • next_prev：包含導覽列中的上一個和下一個按鈕。
  • repo：包含導覽列中的存放庫連結。
  • content：包含頁面的頁面內容和目錄。
  • footer：包含頁面頁尾。

您可能需要查看原始範本檔案，以確保您的修改能與網站結構搭配。請參閱 範本變數，以取得您能在自訂區塊中使用的變數清單。如需更完整的區塊說明，請查看 Jinja 文件。

結合自訂目錄與範本區塊

將 JavaScript 程式庫新增至 custom_dir 可讓程式庫可以使用，但不會將它納入 MkDocs 所產生的頁面中。因此，需要從 HTML 新增一個連結到該程式庫。

從上方的目錄結構開始 (已截斷)

- docs/
- custom_theme/
  - js/
    - somelib.js
- config.yml

需要在範本中新增連結至 custom_theme/js/somelib.js 檔案。由於 somelib.js 是 JavaScript 程式庫，在邏輯上會放置在 libs 區塊中。然而，僅包含新指令碼的新 libs 區塊會取代父範本中定義的區塊，且與父範本中程式庫的所有連結都會移除。若要避免範本毀損，可使用 超級區塊，並從區塊內呼叫 super

{% extends "base.html" %}

{% block libs %}
    {{ super() }}
    <script src="{{ base_url }}/js/somelib.js"></script>
{% endblock %}

請注意，base_url 範本變數可用於確保連結永遠相對於目前頁面。

現在，已產生的頁面將包含連結至範本提供的程式庫，以及包含在 custom_dir 中的程式庫。如果在 custom_dir 中包含任何額外 CSS 檔案，也會需要進行同樣的動作。