在 Markdown 中使用 JavaScript

雖然 Markdown 主要是一種用於格式化文字的標記語言，但你可以通過 JavaScript 增強 Markdown 文檔，添加互動性和動態功能。

理解限制

標準的 Markdown 解析器不會執行 JavaScript 代碼。然而，有幾種方法可以將 JavaScript 與 Markdown 整合：

1. HTML Script 標籤：直接在 HTML 塊中包含 JavaScript
2. Markdown 處理器：使用支持 JavaScript 執行的處理器
3. 靜態網站生成器：利用構建時的 JavaScript 處理
4. 客戶端渲染：在 Markdown 轉換為 HTML 後添加 JavaScript

基本 JavaScript 整合

內聯腳本標籤

你可以使用 HTML script 標籤直接在 Markdown 中嵌入 JavaScript：

# 我的互動式文檔

<script>
function greet() {
  alert('來自 Markdown 的問候！');
}
</script>

<button onclick="greet()">點擊我</button>

外部腳本

引用外部 JavaScript 文件：

<script src="https://cdn.example.com/script.js"></script>

<div id="dynamic-content"></div>

常見用例

1. 互動式表單

# 聯絡表單

<form id="contactForm">
  <input type="text" id="name" placeholder="您的姓名">
  <input type="email" id="email" placeholder="您的電郵">
  <button type="submit">提交</button>
</form>

<script>
document.getElementById('contactForm').addEventListener('submit', function(e) {
  e.preventDefault();
  const name = document.getElementById('name').value;
  alert('謝謝，' + name + '！');
});
</script>

2. 動態內容加載

# 最新文章

<div id="posts-container"></div>

<script>
fetch('/api/posts')
  .then(response => response.json())
  .then(posts => {
    const container = document.getElementById('posts-container');
    posts.forEach(post => {
      container.innerHTML += `<h3>${post.title}</h3><p>${post.excerpt}</p>`;
    });
  });
</script>

3. 數據可視化

# 銷售圖表

<canvas id="salesChart" width="400" height="200"></canvas>

<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
const ctx = document.getElementById('salesChart').getContext('2d');
new Chart(ctx, {
  type: 'line',
  data: {
    labels: ['1月', '2月', '3月', '4月'],
    datasets: [{
      label: '銷售額',
      data: [12, 19, 3, 5]
    }]
  }
});
</script>

靜態網站生成器整合

Jekyll

Jekyll 不在構建時執行 JavaScript，但你可以在佈局中包含它：

---
layout: default
---

{{ content }}

<script>
  // 你的 JavaScript 代碼
</script>

Gatsby

Gatsby 支持在 MDX 中使用 React 組件：

import { useState } from 'react'

export const Counter = () => {
  const [count, setCount] = useState(0)
  return <button onClick={() => setCount(count + 1)}>計數: {count}</button>
}

# 我的文檔

<Counter />

Next.js

在 Next.js 中使用 MDX 實現完整的 React 整合：

import dynamic from 'next/dynamic'

const DynamicComponent = dynamic(() => import('../components/MyComponent'))

# 互動式內容

<DynamicComponent />

安全注意事項

XSS 防護

在 Markdown 中使用 JavaScript 時，始終清理用戶輸入：

// 不好：直接 HTML 注入
element.innerHTML = userInput;

// 好：使用 textContent 或清理
element.textContent = userInput;
// 或者
element.innerHTML = DOMPurify.sanitize(userInput);

內容安全策略

實施 CSP 頭來限制腳本執行：

<meta http-equiv="Content-Security-Policy" 
      content="script-src 'self' https://trusted-cdn.com;">

最佳實踐

1. 分離 JavaScript：盡可能將 JavaScript 存儲在外部文件中
2. 漸進增強：確保內容在沒有 JavaScript 時也能工作
3. 使用 CDN：從 CDN 加載流行的庫以獲得更好的緩存
4. 最小化內聯腳本：使用事件委託而不是內聯處理程序
5. 文檔化依賴：清楚地說明所需的 JavaScript 庫

結論

雖然 Markdown 本身不執行 JavaScript，但你可以有效地結合這兩種技術來創建豐富的互動式文檔。選擇最適合你用例的方法，始終優先考慮安全性和用戶體驗。

其他資源

• MDN JavaScript 指南
• Markdown-it 文檔
• MDX 文檔
• JavaScript 安全最佳實踐