說明文件小工具

文件小工具可簡化文件中的資訊，並提供單一來源。

Fuchsia.dev 說明文件小工具是使用 Jinja2 巨集建立，也支援 Markdown 格式。系統會在頁面發布至 fuchsia.dev 前，將小工具從 Markdown 轉換為實際的 Jinja2 巨集。如要進一步瞭解 Jinja2 巨集，請參閱巨集。

所有說明文件小工具都會在 //docs/_common/_doc_widgets.md 中定義。

先決條件：(僅適用於 HTML/Jinja2)

如要在 HTML/Jinja2 中使用說明文件小工具，必須先將小工具匯入 Markdown (.md) 檔案。請在檔案頂端指定下列項目：


{% import 'fuchsia-src/_common/_doc_widgets.md' as widgets %}

一般小工具

inline_toc

根據 _toc.yaml 檔案建立目錄的項目符號清單。

範例

用量

由於限制，您無法將 _toc.yaml 檔案指定為小工具的參數。


{% set tocmeta | yamlloads %}
{% include "_toc_file.yaml" %}
{% endset %}
{{ widgets.inline_toc () }}

參數

這個小工具不會使用參數，請務必先指定必要條件，再使用這個小工具。

詞彙解釋

這些小工具專為搭配 //docs/glossary/glossary.yaml 中定義的字彙表字詞使用而建立。

如要啟用滑鼠懸停定義，請務必使用下列其中一種語法。建議使用 Markdown 版本。如果使用任何其他語法，系統只會顯示簡單的連結，不會提供滑鼠懸停定義。

如要進一步瞭解如何將字詞新增至詞彙表，請參閱「新增詞彙表項目」。

glossary_simple

建立字詞的懸停定義，並提供詞彙表字詞的連結。這個字詞也可以選擇不提供連結。short_description

範例

  • 可點選的滑鼠懸停定義：

    最終顯示的內容

    定義 ABI <0x0A

  • 不可點按的滑鼠懸停定義：

    最終顯示的內容

    「ABI」的定義

用量

使用這個小工具的方法有幾種：

Markdown

  • 交叉參考連結 (建議)：
[display_name][glossary.term]

或者，您也可以不必指定 display_name，這樣實際的字詞就會做為 display_name 使用：

[glossary.term]

無論採用哪種格式，都必須在 Markdown 檔案底部定義 Xref。例如：

[glossary.display_name]: /docs/glossary/README.md#term
  • 內嵌連結：
[display_name](/docs/glossary/README.md#term)
  • 內嵌連結 (縮短)：
[display_name](/docs/glossary#term)

HTML/Jinja2

{{ widgets.glossary_simple ('term', 'display_name', 'notClickable')}}

參數

Markdown

參數
display_name 必要

在 Markdown 檔案中指定要顯示懸停文字的文字。

使用 [glossary.term] 的 xref 語法時，不需要提供這個值。在這種情況下，詞彙表字詞會做為 display_name。
term 必要
指定 __glossary.yaml 檔案中定義的字詞。

HTML/Jinja2

參數
term 必要
指定 __glossary.yaml 檔案中定義的字詞。
display_name 選用
在 Markdown 檔案中指定要顯示懸停文字的文字。
notClickable 選用
如果使用 display_name，則為必要項目。決定字詞是否要連結至完整詞彙表。如未指定，該字詞會變成可點選，並連結至詞彙表條目。

glossary_box

建立字詞的定義方塊 full_description。如果字詞沒有 full_description，則會使用 short_description。

定義方塊也會顯示編輯按鈕，供貢獻者編輯詞彙表。

範例

  • 定義方塊：

    最終顯示的內容

用量

使用這個小工具的方法有幾種：

Markdown

  • 交叉參考連結 (建議)：
[display_name][glossary.box.term]

然後，您必須在 Markdown 檔案底部定義 Xref。例如：

[glossary.box.display_name]: /docs/glossary/README.md#term
  • 內嵌連結：
[display_name](/docs/glossary/README.md?style=box#term)
  • 內嵌連結 (縮短)：
[display_name](/docs/glossary?style=box#term)

HTML/Jinja2

{{ widgets.glossary_box ('term', 'display_name') }}

參數

參數
term 必要
指定 _glossary.yaml 檔案中定義的字詞。
display_name 必要
：這個參數是避免發生錯誤的必要條件，但不會執行任何動作。