Markdown 中的 Shortcodes

Shortcodes 是一種特殊的語法，允許你在 Markdown 文檔中嵌入複雜的功能，而無需編寫完整的 HTML 或 JavaScript 代碼。它們像是內容模板的快捷方式。

什麼是 Shortcodes？

Shortcodes 是由靜態網站生成器（如 Hugo、Jekyll、Gatsby）提供的簡短代碼片段，可以在 Markdown 中調用預定義的功能或組件。

基本語法

不同平臺的 shortcode 語法略有不同：

Hugo

{{< shortcode-name param1="value1" >}}

{{< shortcode-name param1="value1" >}}
內容
{{< /shortcode-name >}}

Jekyll

{% shortcode_name param1='value1' %}

{% shortcode_name param1='value1' %}
內容
{% endshortcode_name %}

Docusaurus / MDX

<ShortcodeName param1="value1" />

<ShortcodeName param1="value1">
  內容
</ShortcodeName>

常見 Shortcodes

圖片和媒體

Hugo 圖片 Shortcode

{{< figure src="/images/example.jpg" title="示例圖片" caption="這是一個示例圖片" >}}

視頻嵌入

{{< youtube "dQw4w9WgXcQ" >}}

{{< vimeo "123456789" >}}

{{< bilibili "BV1xx411c7mD" >}}

音頻播放器

{{< audio src="/audio/podcast.mp3" >}}

提示和警告框

{{< note >}}
這是一個提示信息。
{{< /note >}}

{{< warning >}}
這是一個警告信息。
{{< /warning >}}

{{< danger >}}
這是一個危險警告。
{{< /danger >}}

{{< tip >}}
這是一個小技巧。
{{< /tip >}}

代碼示例

{{< highlight python "linenos=table,hl_lines=2-3" >}}
def hello_world():
    print("Hello")
    print("World")
{{< /highlight >}}

{{< code-tabs >}}
{{< code-tab lang="javascript" >}}
console.log("Hello World");
{{< /code-tab >}}
{{< code-tab lang="python" >}}
print("Hello World")
{{< /code-tab >}}
{{< /code-tabs >}}

選項卡

{{< tabs >}}
{{< tab "選項卡 1" >}}
這是選項卡 1 的內容。
{{< /tab >}}
{{< tab "選項卡 2" >}}
這是選項卡 2 的內容。
{{< /tab >}}
{{< /tabs >}}

摺疊面板

{{< collapse "點擊展開詳情" >}}
這裡是摺疊的內容。
只有在用戶點擊時才會顯示。
{{< /collapse >}}

{{< accordion >}}
{{< accordion-item "問題 1" >}}
答案 1
{{< /accordion-item >}}
{{< accordion-item "問題 2" >}}
答案 2
{{< /accordion-item >}}
{{< /accordion >}}

創建自定義 Shortcodes

Hugo 自定義 Shortcode

簡單 Shortcode

layouts/shortcodes/highlight-box.html：

<div class="highlight-box">
  {{ .Inner | markdownify }}
</div>

使用：

{{< highlight-box >}}
這是**重要**內容。
{{< /highlight-box >}}

帶參數的 Shortcode

layouts/shortcodes/alert.html：

<div class="alert alert-{{ .Get "type" }}">
  <strong>{{ .Get "title" }}</strong>
  {{ .Inner }}
</div>

使用：

{{< alert type="warning" title="注意" >}}
請小心操作！
{{< /alert >}}

Jekyll 自定義標籤

簡單標籤

_plugins/highlight_tag.rb：

module Jekyll
  class HighlightTag < Liquid::Block
    def render(context)
      content = super
      "<div class='highlight-box'>#{content}</div>"
    end
  end
end

Liquid::Template.register_tag('highlight', Jekyll::HighlightTag)

使用：

{% highlight %}
重要內容
{% endhighlight %}

MDX 自定義組件

React 組件

components/Callout.jsx：

export default function Callout({ type, title, children }) {
  const colors = {
    info: 'blue',
    warning: 'yellow',
    error: 'red',
    success: 'green'
  };
  
  return (
    <div className={`callout callout-${colors[type]}`}>
      {title && <strong>{title}</strong>}
      <div>{children}</div>
    </div>
  );
}

使用：

import Callout from '@/components/Callout';

<Callout type="warning" title="注意">
這是一個重要的警告信息。
</Callout>

最佳實踐

1. 保持簡潔

# 好的：簡潔清晰
{{< note >}}
重要提示
{{< /note >}}

# 避免：過於複雜
{{< container type="note" style="background:blue;padding:20px" id="note-1" class="custom" >}}
重要提示
{{< /container >}}

2. 提供清晰的參數

# 好的：明確的參數名
{{< video src="video.mp4" poster="thumbnail.jpg" width="800" >}}

# 避免：模糊的參數
{{< video "video.mp4" "thumbnail.jpg" "800" >}}

3. 文檔化你的 Shortcodes

創建 shortcode 文檔：

# Shortcode 參考

## note

創建一個提示框。

**語法**：
\`\`\`
{{< note >}}
你的內容
{{< /note >}}
\`\`\`

**參數**：無

**示例**：
\`\`\`
{{< note >}}
這是一個重要提示。
{{< /note >}}
\`\`\`

結論

Shortcodes 是擴展 Markdown 功能的強大工具。它們讓你能夠在保持內容可讀性的同時，添加豐富的互動功能。選擇適合你平臺的 shortcode 系統，並遵循最佳實踐來創建可維護的內容。

其他資源

• Hugo Shortcodes 文檔
• Jekyll Liquid 標籤
• MDX 文檔
• Docusaurus MDX 和 React