`sphinx.ext.extlinks` – 縮短外部連結的標記¶

模組作者：Georg Brandl

在版本 1.0 中新增。

此擴充功能旨在協助處理常見的模式，即擁有許多外部連結指向同一個網站上的 URL，例如指向錯誤追蹤器、版本控制 Web 介面，或僅僅是其他網站中的子頁面。它透過提供基本 URL 的別名來做到這一點，以便您在建立連結時只需要提供子頁面名稱。

假設您想要包含許多指向 Sphinx 追蹤器中 issue 的連結，網址為 https://github.com/sphinx-doc/sphinx/issues/num。一遍又一遍地輸入此 URL 很繁瑣，因此您可以使用 extlinks 來避免重複自己。

此擴充功能新增了一個設定值

extlinks¶

此設定值必須是一個外部網站的字典，將唯一的簡短別名對應到基本 URL 和標題。例如，若要為上述提及的 issue 建立別名，您會新增

extlinks = {'issue': ('https://github.com/sphinx-doc/sphinx/issues/%s',
                      'issue %s')}

現在，您可以使用別名作為新的角色，例如 :issue:`123`。然後，這會插入一個連結到 https://github.com/sphinx-doc/sphinx/issues/123。如您所見，角色中給定的目標會替換基本 URL 中 %s 的位置。

連結標題取決於元組中的第二個項目，即標題

如果標題為 None，則連結標題為完整 URL。
如果標題是一個字串，則它必須正好包含一次 %s。在這種情況下，連結標題是標題，其中部分 URL 替換了 %s – 在上面的範例中，連結標題將會是 issue 123。

若要在基本 URL 或標題中產生 literal %，請使用 %%

extlinks = {'KnR': ('https://example.org/K%%26R/page/%s',
                      '[K&R; page %s]')}

您也可以使用其他產生連結的角色所支援的常用「明確標題」語法，即 :issue:`this issue <123>`。在這種情況下，標題無關緊要。

在版本 4.0 中變更：支援在標題中以 ‘%s’ 替換。

注意

由於連結是在讀取階段從角色產生的，因此它們會顯示為普通連結，例如 linkcheck 建構器。

extlinks_detect_hardcoded_links¶

如果啟用，當硬編碼連結可被 extlink 取代時，extlinks 會發出警告，並透過警告建議替換。

在版本 4.5 中新增。

sphinx.ext.extlinks – 縮短外部連結的標記¶