🧪 TL;DR
<n8n-demo> 是官方推出的 Web Component，可以把 n8n workflow 直接嵌入網頁，讓讀者不用進 n8n 編輯器也能理解流程。本文教你怎麼在 Hugo 網站中啟用這個功能，從設定 unsafe HTML、建立 shortcode 到把 workflow JSON 編碼成可用格式。適合想要在技術部落格中分享 n8n 範例的你。
✨ 什麼是 <n8n-demo> 組件？
<n8n-demo> 是官方提供的 Web Component，可用來視覺化預覽 n8n 的 workflow。這可以直接在網頁中嵌入一個互動式流程圖，讓讀者不必進入 n8n 編輯器，也能快速理解整體流程邏輯。
如果沒有這個組件，要達到同樣的效果可能會非常繁瑣。就必須要：
- 匯出 workflow JSON
- 截圖或自行繪製流程圖
- 解釋每個節點如何運作
- 或嵌入 iframe 指向 n8n 編輯器（但這通常不公開）
有了 <n8n-demo>，只需要貼上 workflow JSON 編碼成 URL 的格式，就能直接顯示清晰的圖形介面，大幅減少說明成本，也讓讀者更容易理解。
✅ 步驟一：設定 Hugo 允許 HTML
在 config.toml 中啟用 unsafe HTML，否則 Markdown 中的 <script>、<n8n-demo> 等 HTML 會被過濾。
[markup]
[markup.goldmark]
[markup.goldmark.renderer]
unsafe = true
✅ 步驟二：建立 Shortcode（可選）
為了避免每篇文章都重複貼 <script>，建議建立 Shortcode。
- 新增檔案：
layouts/shortcodes/n8n-demo.html
- 內容如下：
<script type="module">
import 'https://cdn.jsdelivr.net/npm/@n8n_io/n8n-demo-component@1.0.13/dist/n8n-demo-component.js';
</script>
<n8n-demo workflow="{{ .Get "workflow" }}" frame="true"></n8n-demo>
在 markdown 的程式碼區塊 ``` 也會被渲染成 shortcode，如果沒有很多篇文章都放 workflow 可以在那篇文章開頭加上
<script>就可以。
✅ 步驟三：將 workflow JSON 編碼成 URL 格式
你不能直接貼 JSON，因為 HTML 屬性中不能包含 {} 等特殊字元。你需要使用 encodeURIComponent。
使用瀏覽器 Console 編碼
- 按 F12 開 Console
- 輸入以下（用你自己的 JSON）：
encodeURIComponent(`{"nodes":[{"name":"Workflow-Created","type":"n8n-nodes-base.webhook","position":[512,369],"parameters":{"path":"webhook","httpMethod":"POST"},"typeVersion":1}],"connections":{}}`)
- 拷貝輸出的結果（會是一串
%7B...%7D）
使用 Python 進行 URL 編碼
如果你的系統中安裝了 Python，可以利用 Python 自帶的 urllib 庫來進行 URL 編碼：
python -c "import urllib.parse; print(urllib.parse.quote('{"nodes":[{"name":"Workflow-Created","type":"n8n-nodes-base.webhook","position":[512,369],"parameters":{"path":"webhook","httpMethod":"POST"},"typeVersion":1}],"connections":{}}'))"
這條命令會將你的 JSON 字符串進行 URL 編碼，並輸出編碼後的結果。
使用 Node.js 進行 URL 編碼
如果你安裝了 Node.js，使用以下命令進行 URL 編碼：
node -e "console.log(encodeURIComponent('{\"nodes\":[{\"name\":\"Workflow-Created\",\"type\":\"n8n-nodes-base.webhook\",\"position\":[512,369],\"parameters\":{\"path\":\"webhook\",\"httpMethod\":\"POST\"},\"typeVersion\":1}],\"connections\":{}}'))"
這條命令會將 JSON 編碼成 URL 可用格式。
使用 Linux 或 MacOS 的命令行工具
如果你使用的是 Linux 或 macOS，這裡有一個簡單的命令可以進行 URL 編碼：
echo -n '{"nodes":[{"name":"Workflow-Created","type":"n8n-nodes-base.webhook","position":[512,369],"parameters":{"path":"webhook","httpMethod":"POST"},"typeVersion":1}],"connections":{}}' | jq -sRr @uri
這條命令會使用 jq 來處理並將 JSON 編碼為 URL 格式。如果你的系統尚未安裝 jq，可以先安裝：
sudo apt install jq # Ubuntu/Debian
brew install jq # MacOS
使用 線上工具 進行編碼
如果你不希望安裝任何東西，還可以使用在線 URL 編碼工具。這些網站可以幫助你快速將 JSON 字符串轉換為 URL 編碼格式。例如：
只需將 JSON 貼入，然後將編碼結果複製過來。
✅ 步驟四：在文章中使用
你可以這樣插入：
<!-- 這裡放在文章開頭 -->
<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2.0.0/webcomponents-loader.js"></script>
<script src="https://www.unpkg.com/lit@2.0.0-rc.2/polyfill-support.js"></script>
<script type="module" src="https://cdn.jsdelivr.net/npm/@n8n_io/n8n-demo-component/n8n-demo.bundled.js"></script>
<!-- 這裡放在要顯示 workflow 的地方 -->
<n8n-demo
workflow="%7B%22nodes%22%3A%5B%7B%22name%22%3A%22Workflow-Created%22%2C%22type%22%3A%22n8n-nodes-base.webhook%22%2C%22position%22%3A%5B512%2C369%5D%2C%22parameters%22%3A%7B%22path%22%3A%22webhook%22%2C%22httpMethod%22%3A%22POST%22%7D%2C%22typeVersion%22%3A1%7D%5D%2C%22connections%22%3A%7B%7D%7D"
frame="true">
</n8n-demo>
這樣會在頁面上顯示一個可互動的 n8n workflow preview。
✅ 渲染效果如下
Reference
- <n8n-demo> — Workflow preview web component
- OpenAI ChatGPT — 協助流程說明與內容撰寫