文件Experience Cloud KCS

AEM Guides：xref在連結中使用mailto：#時，網站產生失敗

最後更新： 2026年6月25日

本文解決當xref包含以#字元開頭的mailto連結時，Adobe Experience Manager Guides中的網站產生失敗。

說明 description

環境

Adobe Experience Manager Guides （所有版本）
問題/症狀

使用預設集產生AEM Sites輸出時，如果xref元素包含以#字元開頭的mailto連結（例如： mailto:#example@example.com），則程式會失敗。

產生網站期間發生下列錯誤：

BUILD FAILED
/mnt/crx/author/crx-quickstart/profiles/ditaot--<profile-id>/DITA-OT/plugins/org.dita.base/build_preprocess.xml:62:
Failed to run pipeline: Expected scheme-specific part at index 7: mailto:#example@example.com
  • 您可以在任何主題中新增具有mailto:#的xref，並嘗試產生AEM Sites輸出，以重現此問題。
  • 在DITA-OT預先處理步驟期間發生錯誤。

如需其他內容，請參閱DITA URI型定址檔案：

解決方法 resolution

  1. 更新xref元素以使用#字元的百分比編碼。
    不要使用< xref> mailto:#example@example.com​< /xref>將#編碼為%23。

    例如:

    code language-none 
    <xref href="mailto:%23example@example.com" format="html">Contact Support</xref>

​2. Ensure the xref uses the href attribute and includes display text.

  • This helps DITA-OT correctly interpret the link as an external reference.
    ​3. Save the topic and regenerate the AEM Sites output using Presets.
  • The site generation should now complete successfully without errors.

Cause

The DITA-OT processor interprets the # character as a fragment identifier within URIs. When used directly in a mailto link, it causes URI parsing errors. Percent-encoding the # character as %23 allows DITA-OT to process the link as intended.

recommendation-more-help
experience-cloud-kcs-help-kbarticles