> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/build/choose-channel/web-chat/markdown-rendering.md).

# Markdown 渲染

Web Chat 訊息內容渲染：Markdown 標題、清單、表格、程式碼區塊與連結在聊天視窗的呈現方式、優化項目與管理員設定。

本篇將介紹 Web Chat 聊天視窗中訊息內容渲染的優化功能，讓 Agent 的回答呈現更清晰、更易讀。

## 什麼是訊息內容渲染？ <a href="#what-is-message-rendering" id="what-is-message-rendering"></a>

訊息內容渲染是指 Web Chat 如何將 Agent 的文字回答轉換成使用者看到的視覺呈現。Agent 的回答可能包含：

* **純文字**：一般的文字敘述
* **Markdown 格式**：包含標題、列表、粗體、斜體等格式
* **程式碼區塊**：程式碼範例或指令
* **表格**：結構化的資料呈現
* **連結**：外部連結或參考資料

良好的渲染效果能讓這些內容更容易閱讀和理解。

## 優化項目 <a href="#optimization-items" id="optimization-items"></a>

### 1. 全面升級 Markdown 渲染引擎 <a href="#upgrade-markdown-rendering-engine" id="upgrade-markdown-rendering-engine"></a>

Web Chat 現已採用增強型 Markdown 渲染引擎，支援更豐富的格式和更精確的渲染效果。

#### 支援的 Markdown 格式 <a href="#supported-markdown-formats" id="supported-markdown-formats"></a>

| 格式類型      | 語法範例                                     | 渲染效果說明                                            |
| --------- | ---------------------------------------- | ------------------------------------------------- |
| **標題**    | `# 標題一`、`## 標題二`                         | 清晰的標題層級，方便內容分段                                    |
| **粗體**    | `**粗體文字**`                               | 強調重點內容                                            |
| **斜體**    | `*斜體文字*`                                 | 次要強調或補充說明                                         |
| **列表**    | `- 項目一`、`1. 項目一`                         | 有序或無序列表                                           |
| **程式碼**   | `` `程式碼` ``                              | 行內程式碼或指令                                          |
| **程式碼區塊** | ` ```程式碼``` `                            | 多行程式碼，支援語法高亮                                      |
| **表格**    | `\| 欄位一 \| 欄位二 \|`                       | 結構化資料呈現                                           |
| **連結**    | `[連結文字](網址)`                             | 可點擊的超連結                                           |
| **引用**    | `> 引用內容`                                 | 引用或特別說明                                           |
| **圖片**    | `![說明](圖片網址)`、`![說明](圖片網址){width=200px}` | 顯示圖片；網址後緊接 `{…}` 可指定顯示尺寸，見[調整圖片顯示尺寸](#image-size) |

#### 連結與檔案連結的行為 <a href="#link-behavior" id="link-behavior"></a>

* 回答中的連結一律在**新分頁**開啟，不會離開目前的對話（只有頁內錨點 `#…` 例外）。
* 連結指向 PDF 或其他檔案時，怎麼開由瀏覽器決定：Chrome、Edge、Safari 會在新分頁用內建檢視器開啟 PDF，`https://example.com/manual.pdf#page=12` 這類帶頁碼的網址會直接跳到該頁；瀏覽器設定為下載 PDF 時則會下載，Web Chat 不會改寫網址或強制下載。
* 要讓 Agent 回「文字連結＋頁碼」而不是附件：把文件網址（含頁碼）寫進知識庫文件的 `url` 元資料或 FAQ 答案，並在角色指令要求以 Markdown 連結回覆，見 [自訂連結映射](/build/knowledge-base/tags-and-metadata.md#custom-url-mapping)。引用來源的文件下載是另一條路，由[功能設定](/build/conversation-settings/platform-settings/function-settings.md#ai-interaction)的「允許下載引用文件」控制。

#### 調整圖片顯示尺寸 <a href="#image-size" id="image-size"></a>

Agent 回覆中的 Markdown 圖片預設以原圖大小顯示，最寬到訊息欄寬。在圖片網址的右括號後面緊接一段 `{width=…}` 或 `{height=…}`，就能指定這張圖的顯示尺寸。Web Chat 與後台的對話畫面（例如從 <mark style="color:blue;">Agent 市集</mark> 按 <mark style="color:blue;">開始對話</mark>）都支援。

例如電商的客服主管發現，Agent 回覆商品圖時一張圖就佔滿整個聊天視窗，顧客要一直往下捲才看得到文字。她在 Agent 的角色指令中要求商品圖一律以 `![商品圖](圖片網址){width=200px}` 的格式輸出（填寫位置見[為 Agent 加入角色指令](/build/agent/add-system-prompt.md)）。之後顧客在官網 Web Chat 看到的商品圖寬度固定為 200px，同事在後台和同一個 Agent 對話時看到的也是同樣大小。

```markdown
![示範圖](https://example.com/a.png){width=200px}
![示範圖](https://example.com/a.png){width=50%}
![示範圖](https://example.com/a.png){width=300px height=200px}
```

| 規則      | 說明                                               |
| ------- | ------------------------------------------------ |
| 可用的設定   | 只有 `width`（寬）與 `height`（高），一律小寫，各最多寫一次，順序不限      |
| 單位      | `px` 或 `%`，數值須大於 0，可帶小數（例如 `33.5%`）；`%` 不可超過 100 |
| 百分比的基準  | `%` 以訊息欄的寬度計算                                    |
| 同時設定寬與高 | 兩個設定之間用空白隔開（`{width=300px height=200px}`），不能用逗號  |
| 只設定其中一個 | 另一邊依原圖比例自動調整                                     |
| 位置      | `{` 必須緊接在網址的 `)` 後面，中間不能有空白                      |
| 超過訊息欄寬度 | 會自動縮到訊息欄寬度以內，圖片不會變形                              |

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-e18a774c18e95e36101cf37ba44999d4bcaca551%2Fmarkdown-image-size-web-chat.png?alt=media" alt="Web Chat 中 Agent 回覆兩張相同的圖片，第一張以原始尺寸顯示，第二張標示指定寬度 200px，顯示得較小"><figcaption><p>Web Chat：同一張圖，未指定尺寸（上）與 <code>{width=200px}</code>（下）</p></figcaption></figure>

<figure><img src="https://1593648278-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fmzb5NG9GDzFP2YDKeYVl%2Fuploads%2Fgit-blob-ce27aa9a902bab5a4940ac86f0a2f1b8646949b4%2Fmarkdown-image-size-admin-chat.png?alt=media" alt="後台對話畫面中 Agent 回覆兩張相同的圖片，第一張以原始尺寸顯示，第二張標示指定寬度 200px，顯示得較小"><figcaption><p>後台對話畫面：同樣的回覆，第二張圖寬度為 200px</p></figcaption></figure>

{% hint style="warning" %}
`{…}` 內只要有一處不符合上表規則（例如 `{width=150%}`、`{size=200px}`、`)` 和 `{` 之間有空白、少了右大括號），整段尺寸設定都不會套用：圖片以預設大小顯示，`{…}` 文字原樣出現在訊息中。寫在程式碼或程式碼區塊裡的 `{width=…}` 也會原樣顯示。
{% endhint %}

{% hint style="info" %}
尺寸設定只在 Web Chat 與後台對話畫面生效。LINE、Messenger、Instagram、WhatsApp 等通訊軟體通道不會套用，圖片後面的 `{width=…}` 會以文字留在訊息中；同一個 Agent 也服務這些通道時，建議不要在角色指令中要求使用尺寸語法。
{% endhint %}

### 2. 深色模式視覺優化 <a href="#dark-mode-visual-optimization" id="dark-mode-visual-optimization"></a>

當終端使用者的裝置使用深色主題時，Web Chat 會自動調整訊息內容的視覺呈現，確保在深色背景下的清晰度和可讀性。

#### 深色模式調整項目 <a href="#dark-mode-adjustment-items" id="dark-mode-adjustment-items"></a>

1. **文字與背景對比度**：自動調整文字顏色，確保在深色背景下清楚顯示
2. **訊息反饋按鈕**：調整按鈕的顏色和邊框，在深色模式下仍保持清晰
3. **表格視覺呈現**：調整表格邊框和背景色，提高可讀性
4. **引用區塊背景**：調整引用區塊的背景色調，與主要內容做出區隔

### 3. 串流渲染效能提升 <a href="#streaming-rendering-performance" id="streaming-rendering-performance"></a>

Web Chat 採用即時串流方式顯示 Agent 的回答，讓使用者不需等待完整回答產生完畢。本次更新優化了串流渲染的效能：

* **渲染速度提升**：Markdown 格式的渲染速度更快，減少延遲感
* **流暢度改善**：文字逐字顯示時更流暢，無明顯卡頓
* **格式正確性**：即使在串流過程中，Markdown 格式也能正確渲染

{% hint style="success" %}
使用者可以在 Agent 回答的過程中，即時看到已經產生的內容，不需等待完整回答。
{% endhint %}

## 實際應用場景 <a href="#use-cases" id="use-cases"></a>

### 💻 技術文件助理 <a href="#technical-documentation-assistant" id="technical-documentation-assistant"></a>

**使用情境**： 開發者詢問程式碼範例時，Agent 提供包含程式碼區塊的回答。

**優化效果**：

* 程式碼區塊支援語法高亮，更容易閱讀
* 深色模式下程式碼清晰顯示
* 開發者可以直接複製程式碼使用

**範例回答**：

````
以下是 Python 讀取 CSV 檔案的範例：

```python
import pandas as pd

df = pd.read_csv('data.csv')
print(df.head())
````

這段程式碼會讀取 CSV 檔案並顯示前 5 筆資料。

```

### 📊 資料分析助理 <a href="#data-analysis-assistant" id="data-analysis-assistant"></a>

**使用情境**：
使用者詢問銷售數據分析結果，Agent 以表格方式呈現。

**優化效果**：
* 表格格式清晰，欄位對齊
* 深色模式下表格邊框和背景色適配
* 大量資料也能保持可讀性

**範例回答**：
```

以下是本季銷售前三名的產品：

| 產品名稱 | 銷售數量  | 銷售額      |
| ---- | ----- | -------- |
| 產品 A | 1,250 | $125,000 |
| 產品 B | 980   | $98,000  |
| 產品 C | 856   | $85,600  |

銷售數據截至本月 20 日。

```

### 📚 教學助理 <a href="#tutorial-assistant" id="tutorial-assistant"></a>

**使用情境**：
學生詢問學習步驟，Agent 以有序列表方式說明。

**優化效果**：
* 列表項目清楚編號
* 標題層級分明，方便理解步驟順序
* 重點內容使用粗體強調

**範例回答**：
```

## 學習 Python 的建議步驟

1. **基礎語法**
   * 變數和資料型別
   * 條件判斷和迴圈
2. **進階概念**
   * 函數和模組
   * 物件導向程式設計
3. **實作練習**
   * 完成小型專案
   * 參與開源貢獻

每個步驟建議花費 2-3 週時間學習。

```

## 管理員設定 <a href="#admin-settings" id="admin-settings"></a>

### Markdown 渲染設定 <a href="#markdown-rendering-settings" id="markdown-rendering-settings"></a>

Web Chat 的 Markdown 渲染功能預設為啟用狀態。如果您的使用情境不需要 Markdown 格式，可以在設定中調整：

1. 進入「發布」→「Web Chat 設定」
2. 找到「訊息渲染」設定區塊
3. 選擇渲染模式：
   * **完整 Markdown**：支援所有 Markdown 格式（預設）
   * **基本格式**：僅支援粗體、斜體、連結
   * **純文字**：不渲染任何格式

### 深色模式設定 <a href="#dark-mode-settings" id="dark-mode-settings"></a>

深色模式會自動依據使用者裝置設定啟用。如果您希望讓 Web Chat 固定使用淺色或深色主題：

1. 進入「發布」→「Web Chat 設定」
2. 找到「外觀」設定區塊
3. 選擇主題模式：
   * **自動**：依據使用者裝置設定（預設）
   * **淺色**：固定使用淺色主題
   * **深色**：固定使用深色主題

<div data-gb-custom-block data-tag="hint" data-style='info'>

Web Chat 外觀設定的詳細說明請參考：[串接對話平台：網站](website.md)

</div>

## 效能影響 <a href="#performance-impact" id="performance-impact"></a>

### 渲染效能 <a href="#rendering-performance" id="rendering-performance"></a>

優化後的 Markdown 渲染引擎對效能的影響：

* **載入時間**：首次載入增加約 0.1-0.2 秒（幾乎無感）
* **記憶體使用**：增加約 1-2 MB（對現代瀏覽器影響極小）
* **渲染速度**：相較舊版提升約 30%

### 相容性 <a href="#compatibility" id="compatibility"></a>

優化後的渲染引擎支援以下瀏覽器：

* Chrome / Edge（版本 90 以上）
* Firefox（版本 88 以上）
* Safari（版本 14 以上）
* 行動裝置瀏覽器（iOS Safari、Android Chrome）

<div data-gb-custom-block data-tag="hint" data-style='warning'>

較舊版本的瀏覽器可能無法正確顯示部分 Markdown 格式，建議提醒使用者更新瀏覽器。

</div>

## 通訊軟體通道：自動轉成純文字 <a href="#messaging-channels-plain-text" id="messaging-channels-plain-text"></a>

本頁的 Markdown 渲染只適用於會顯示富文字的 Web Chat。LINE、Messenger、Instagram、WhatsApp 不渲染 Markdown，Agent 的回覆送到這四個通道前會自動轉換，使用者收到的是乾淨的文字：

| Markdown | 轉換後 |
| --- | --- |
| `# 標題`、`**粗體**`、`*斜體*`、`~~刪除線~~` | 去掉符號只留文字（WhatsApp 的粗體改用它自己的 `*粗體*` 樣式） |
| `[文字](網址)` | 「文字 網址」 |
| 表格 | 每一列變成一行「- 欄名: 值 / 欄名: 值」 |
| 程式碼區塊 | 只留內容 |
| 條列、換行 | 保留 |
| 圖片 `![說明](網址)` | 會另外補發成圖片的那張從文字中移除；不會補發的顯示為「說明 網址」 |

只有 Agent 送出的訊息會轉換；真人客服在後台打的字、LINE Flex 卡片與快速回覆按鈕原樣送出。後台對話頁與報表保存的仍是模型的原始回覆。Viber 通道維持原有的樣式轉換。

例如連鎖藥局的 Agent 同時服務官網 Web Chat 與 LINE，回覆門市營業時間時會用表格整理。官網訪客看到的是表格；LINE 使用者收到的是每間門市一行的「- 門市: 信義店 / 營業時間: 09:00–22:00」條列，不會看到一堆 `|` 與 `**` 符號，因此不需要為 LINE 另外寫一套角色指令。

## 常見問題 <a href="#faq" id="faq"></a>

### Q1：為什麼我的 Agent 回答沒有格式？ <a href="#faq-ai-agent-response-no-format" id="faq-ai-agent-response-no-format"></a>

可能原因：
* Agent 沒有使用 Markdown 語法
* Markdown 渲染功能被停用
* 瀏覽器版本過舊

### Q2：深色模式下某些內容看不清楚怎麼辦？ <a href="#faq-dark-mode-content-visibility" id="faq-dark-mode-content-visibility"></a>

請嘗試：
1. 清除瀏覽器快取
2. 重新整理頁面
3. 確認使用最新版本的瀏覽器

### Q3：程式碼區塊可以自訂語法高亮的顏色嗎？ <a href="#faq-customize-code-block-syntax-highlight" id="faq-customize-code-block-syntax-highlight"></a>

目前語法高亮顏色是固定的，未來版本可能會開放自訂功能。

### Q4：表格內容過長時會怎麼顯示？ <a href="#faq-long-table-display" id="faq-long-table-display"></a>

表格會自動支援橫向捲動，確保內容完整顯示且不影響其他內容的排版。

### Q5：渲染優化會影響行動裝置的顯示嗎？ <a href="#faq-mobile-device-rendering" id="faq-mobile-device-rendering"></a>

不會。渲染優化針對行動裝置也進行了適配，確保在小螢幕上也能清楚顯示。

```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/build/choose-channel/web-chat/markdown-rendering.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.