<?xml version="1.0" encoding="utf-8" standalone="yes"?><rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/"><channel><title>Shortcode on Tarragon</title><link>https://tarrragon.github.io/blog/tags/shortcode/</link><description>Recent content in Shortcode on Tarragon</description><generator>Hugo -- gohugo.io</generator><language>zh-TW</language><copyright>Tarragon (CC BY 4.0)</copyright><lastBuildDate>Thu, 09 Oct 2025 00:00:00 +0000</lastBuildDate><atom:link href="https://tarrragon.github.io/blog/tags/shortcode/index.xml" rel="self" type="application/rss+xml"/><item><title>Hugo Shortcode 實現可折疊區塊</title><link>https://tarrragon.github.io/blog/posts/hugo-shortcode-%E5%AF%A6%E7%8F%BE%E5%8F%AF%E6%8A%98%E7%96%8A%E5%8D%80%E5%A1%8A/</link><pubDate>Thu, 09 Oct 2025 00:00:00 +0000</pubDate><guid>https://tarrragon.github.io/blog/posts/hugo-shortcode-%E5%AF%A6%E7%8F%BE%E5%8F%AF%E6%8A%98%E7%96%8A%E5%8D%80%E5%A1%8A/</guid><description>&lt;h2 id="問題背景">問題背景&lt;/h2>
&lt;p>在撰寫技術文章時，我們會在文章中加入程式碼範例。但是 blog 的目標是分享我處理問題的思路，而不是提供解決方案，所以我希望預設把程式碼隱藏。&lt;/p>
&lt;h3 id="最初的解決方案">最初的解決方案&lt;/h3>
&lt;p>使用 HTML5 的 &lt;code>&amp;lt;details&amp;gt;&lt;/code> 和 &lt;code>&amp;lt;summary&amp;gt;&lt;/code> 標籤：&lt;/p>





&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-html" data-lang="html">&lt;span class="line">&lt;span class="ln">1&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">2&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>點擊查看程式碼&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">3&lt;/span>&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">4&lt;/span>&lt;span class="cl">\```javascript
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">5&lt;/span>&lt;span class="cl">console.log(&amp;#39;Hello World&amp;#39;);
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">6&lt;/span>&lt;span class="cl">\```
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">7&lt;/span>&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">8&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;p>這個方案雖然功能正常，但會觸發 &lt;strong>MD033 Markdown Linter 警告&lt;/strong>：&lt;/p>





&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-text" data-lang="text">&lt;span class="line">&lt;span class="ln">1&lt;/span>&lt;span class="cl">MD033/no-inline-html: Inline HTML [Element: details]&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h2 id="為什麼會有這個警告">為什麼會有這個警告？&lt;/h2>
&lt;h3 id="markdown-設計哲學">Markdown 設計哲學&lt;/h3>
&lt;p>Markdown 的設計理念是：&lt;/p>
&lt;ul>
&lt;li>保持純文字的可讀性&lt;/li>
&lt;li>避免直接使用 HTML 標籤&lt;/li>
&lt;li>使用語義化的標記語法&lt;/li>
&lt;/ul>
&lt;h3 id="md033-規則的目的">MD033 規則的目的&lt;/h3>
&lt;p>MD033 規則旨在：&lt;/p>
&lt;ol>
&lt;li>&lt;strong>維持 Markdown 的純淨性&lt;/strong>：避免 HTML 與 Markdown 混用&lt;/li>
&lt;li>&lt;strong>提升可維護性&lt;/strong>：純 Markdown 更容易閱讀和維護&lt;/li>
&lt;li>&lt;strong>確保相容性&lt;/strong>：不同的 Markdown 渲染器對 HTML 的支援程度不同&lt;/li>
&lt;/ol>
&lt;h2 id="hugo-shortcode-解決方案">Hugo Shortcode 解決方案&lt;/h2>
&lt;h3 id="什麼是-shortcode">什麼是 Shortcode？&lt;/h3>
&lt;p>Hugo Shortcode 是 Hugo 靜態網站生成器提供的一個強大功能，允許你：&lt;/p>
&lt;ul>
&lt;li>在 Markdown 中使用自定義的簡短標記&lt;/li>
&lt;li>封裝複雜的 HTML 結構&lt;/li>
&lt;li>保持 Markdown 文件的整潔&lt;/li>
&lt;/ul>
&lt;h3 id="優勢分析">優勢分析&lt;/h3>
&lt;table>
 &lt;thead>
 &lt;tr>
 &lt;th>特性&lt;/th>
 &lt;th>HTML 標籤&lt;/th>
 &lt;th>Hugo Shortcode&lt;/th>
 &lt;/tr>
 &lt;/thead>
 &lt;tbody>
 &lt;tr>
 &lt;td>Markdown Linter&lt;/td>
 &lt;td>觸發警告&lt;/td>
 &lt;td>無警告&lt;/td>
 &lt;/tr>
 &lt;tr>
 &lt;td>可維護性&lt;/td>
 &lt;td>分散在各處&lt;/td>
 &lt;td>集中管理&lt;/td>
 &lt;/tr>
 &lt;tr>
 &lt;td>可讀性&lt;/td>
 &lt;td>較差&lt;/td>
 &lt;td>優秀&lt;/td>
 &lt;/tr>
 &lt;tr>
 &lt;td>彈性&lt;/td>
 &lt;td>固定結構&lt;/td>
 &lt;td>可自定義&lt;/td>
 &lt;/tr>
 &lt;tr>
 &lt;td>Hugo 最佳實踐&lt;/td>
 &lt;td>不推薦&lt;/td>
 &lt;td>官方推薦&lt;/td>
 &lt;/tr>
 &lt;/tbody>
&lt;/table>
&lt;h2 id="實現步驟">實現步驟&lt;/h2>
&lt;h3 id="步驟-1創建-shortcode-檔案">步驟 1：創建 Shortcode 檔案&lt;/h3>
&lt;p>在專案根目錄創建 &lt;code>layouts/shortcodes/details.html&lt;/code>：&lt;/p>
&lt;details>
 &lt;summary>點擊查看 Shortcode 程式碼&lt;/summary>





&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-html" data-lang="html">&lt;span class="line">&lt;span class="ln"> 1&lt;/span>&lt;span class="cl">{{/* 
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 2&lt;/span>&lt;span class="cl"> Details shortcode - 用於創建可折疊的內容區塊
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 3&lt;/span>&lt;span class="cl"> 
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 4&lt;/span>&lt;span class="cl"> 使用方式:
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 5&lt;/span>&lt;span class="cl"> 
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 6&lt;/span>&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 7&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 8&lt;/span>&lt;span class="cl"> &lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>點擊展開&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 9&lt;/span>&lt;span class="cl"> 
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">10&lt;/span>&lt;span class="cl"> 內容...
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">11&lt;/span>&lt;span class="cl"> 
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">12&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">13&lt;/span>&lt;span class="cl"> 
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">14&lt;/span>&lt;span class="cl"> 參數:
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">15&lt;/span>&lt;span class="cl"> - summary: 摘要文字（可選，預設為 &amp;#34;點擊展開&amp;#34;）
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">16&lt;/span>&lt;span class="cl">*/}}
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">17&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">18&lt;/span>&lt;span class="cl"> &lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>{{ .Get &amp;#34;summary&amp;#34; | default &amp;#34;點擊展開&amp;#34; }}&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">19&lt;/span>&lt;span class="cl"> {{ .Inner | markdownify }}
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">20&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;/details>
&lt;p>&lt;strong>程式碼說明&lt;/strong>：&lt;/p>
&lt;ol>
&lt;li>&lt;strong>註解區塊&lt;/strong>：&lt;code>{{/* ... */}}&lt;/code> 用於說明 shortcode 的用途和使用方式&lt;/li>
&lt;li>&lt;strong>參數獲取&lt;/strong>：&lt;code>.Get &amp;quot;summary&amp;quot;&lt;/code> 獲取 summary 參數&lt;/li>
&lt;li>&lt;strong>預設值&lt;/strong>：&lt;code>default &amp;quot;點擊展開&amp;quot;&lt;/code> 提供預設文字&lt;/li>
&lt;li>&lt;strong>內容處理&lt;/strong>：&lt;code>.Inner&lt;/code> 獲取標籤內的內容&lt;/li>
&lt;li>&lt;strong>Markdown 渲染&lt;/strong>：&lt;code>markdownify&lt;/code> 將內容中的 Markdown 語法轉換為 HTML&lt;/li>
&lt;/ol>
&lt;h3 id="步驟-2在-markdown-中使用">步驟 2：在 Markdown 中使用&lt;/h3>
&lt;h4 id="舊方式會觸發-md033">舊方式（會觸發 MD033）&lt;/h4>





&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-markdown" data-lang="markdown">&lt;span class="line">&lt;span class="ln"> 1&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 2&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>點擊查看程式碼&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">summary&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 3&lt;/span>&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 4&lt;/span>&lt;span class="cl">\``&lt;span class="sb">`toml
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 5&lt;/span>&lt;span class="cl">&lt;span class="sb">[markup]
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 6&lt;/span>&lt;span class="cl">&lt;span class="sb"> [markup.tableOfContents]
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 7&lt;/span>&lt;span class="cl">&lt;span class="sb"> startLevel = 2
&lt;/span>&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 8&lt;/span>&lt;span class="cl">&lt;span class="sb">\`&lt;/span>``
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln"> 9&lt;/span>&lt;span class="cl">
&lt;/span>&lt;/span>&lt;span class="line">&lt;span class="ln">10&lt;/span>&lt;span class="cl">&lt;span class="p">&amp;lt;/&lt;/span>&lt;span class="nt">details&lt;/span>&lt;span class="p">&amp;gt;&lt;/span>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h4 id="新方式符合-markdown-規範">新方式（符合 Markdown 規範）&lt;/h4>





&lt;div class="highlight">&lt;pre tabindex="0" class="chroma">&lt;code class="language-markdown" data-lang="markdown">&lt;span class="line">&lt;span class="ln">1&lt;/span>&lt;span class="cl">

&lt;details>
 &lt;summary>點擊查看程式碼&lt;/summary>
 

\```toml
[markup]
 [markup.tableOfContents]
 startLevel = 2
\```


&lt;/details>&lt;/span>&lt;/span>&lt;/code>&lt;/pre>&lt;/div>&lt;h3 id="步驟-3添加-css-樣式">步驟 3：添加 CSS 樣式&lt;/h3>
&lt;p>在 &lt;code>layouts/partials/custom_head.html&lt;/code> 中添加樣式：&lt;/p></description><content:encoded><![CDATA[<h2 id="問題背景">問題背景</h2>
<p>在撰寫技術文章時，我們會在文章中加入程式碼範例。但是 blog 的目標是分享我處理問題的思路，而不是提供解決方案，所以我希望預設把程式碼隱藏。</p>
<h3 id="最初的解決方案">最初的解決方案</h3>
<p>使用 HTML5 的 <code>&lt;details&gt;</code> 和 <code>&lt;summary&gt;</code> 標籤：</p>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="ln">1</span><span class="cl"><span class="p">&lt;</span><span class="nt">details</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">2</span><span class="cl"><span class="p">&lt;</span><span class="nt">summary</span><span class="p">&gt;</span>點擊查看程式碼<span class="p">&lt;/</span><span class="nt">summary</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">3</span><span class="cl">
</span></span><span class="line"><span class="ln">4</span><span class="cl">\```javascript
</span></span><span class="line"><span class="ln">5</span><span class="cl">console.log(&#39;Hello World&#39;);
</span></span><span class="line"><span class="ln">6</span><span class="cl">\```
</span></span><span class="line"><span class="ln">7</span><span class="cl">
</span></span><span class="line"><span class="ln">8</span><span class="cl"><span class="p">&lt;/</span><span class="nt">details</span><span class="p">&gt;</span></span></span></code></pre></div><p>這個方案雖然功能正常，但會觸發 <strong>MD033 Markdown Linter 警告</strong>：</p>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="ln">1</span><span class="cl">MD033/no-inline-html: Inline HTML [Element: details]</span></span></code></pre></div><h2 id="為什麼會有這個警告">為什麼會有這個警告？</h2>
<h3 id="markdown-設計哲學">Markdown 設計哲學</h3>
<p>Markdown 的設計理念是：</p>
<ul>
<li>保持純文字的可讀性</li>
<li>避免直接使用 HTML 標籤</li>
<li>使用語義化的標記語法</li>
</ul>
<h3 id="md033-規則的目的">MD033 規則的目的</h3>
<p>MD033 規則旨在：</p>
<ol>
<li><strong>維持 Markdown 的純淨性</strong>：避免 HTML 與 Markdown 混用</li>
<li><strong>提升可維護性</strong>：純 Markdown 更容易閱讀和維護</li>
<li><strong>確保相容性</strong>：不同的 Markdown 渲染器對 HTML 的支援程度不同</li>
</ol>
<h2 id="hugo-shortcode-解決方案">Hugo Shortcode 解決方案</h2>
<h3 id="什麼是-shortcode">什麼是 Shortcode？</h3>
<p>Hugo Shortcode 是 Hugo 靜態網站生成器提供的一個強大功能，允許你：</p>
<ul>
<li>在 Markdown 中使用自定義的簡短標記</li>
<li>封裝複雜的 HTML 結構</li>
<li>保持 Markdown 文件的整潔</li>
</ul>
<h3 id="優勢分析">優勢分析</h3>
<table>
  <thead>
      <tr>
          <th>特性</th>
          <th>HTML 標籤</th>
          <th>Hugo Shortcode</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>Markdown Linter</td>
          <td>觸發警告</td>
          <td>無警告</td>
      </tr>
      <tr>
          <td>可維護性</td>
          <td>分散在各處</td>
          <td>集中管理</td>
      </tr>
      <tr>
          <td>可讀性</td>
          <td>較差</td>
          <td>優秀</td>
      </tr>
      <tr>
          <td>彈性</td>
          <td>固定結構</td>
          <td>可自定義</td>
      </tr>
      <tr>
          <td>Hugo 最佳實踐</td>
          <td>不推薦</td>
          <td>官方推薦</td>
      </tr>
  </tbody>
</table>
<h2 id="實現步驟">實現步驟</h2>
<h3 id="步驟-1創建-shortcode-檔案">步驟 1：創建 Shortcode 檔案</h3>
<p>在專案根目錄創建 <code>layouts/shortcodes/details.html</code>：</p>
<details>
  <summary>點擊查看 Shortcode 程式碼</summary>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="ln"> 1</span><span class="cl">{{/* 
</span></span><span class="line"><span class="ln"> 2</span><span class="cl">  Details shortcode - 用於創建可折疊的內容區塊
</span></span><span class="line"><span class="ln"> 3</span><span class="cl">  
</span></span><span class="line"><span class="ln"> 4</span><span class="cl">  使用方式:
</span></span><span class="line"><span class="ln"> 5</span><span class="cl">  
</span></span><span class="line"><span class="ln"> 6</span><span class="cl">
</span></span><span class="line"><span class="ln"> 7</span><span class="cl"><span class="p">&lt;</span><span class="nt">details</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln"> 8</span><span class="cl">  <span class="p">&lt;</span><span class="nt">summary</span><span class="p">&gt;</span>點擊展開<span class="p">&lt;/</span><span class="nt">summary</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln"> 9</span><span class="cl">  
</span></span><span class="line"><span class="ln">10</span><span class="cl">  內容...
</span></span><span class="line"><span class="ln">11</span><span class="cl">  
</span></span><span class="line"><span class="ln">12</span><span class="cl"><span class="p">&lt;/</span><span class="nt">details</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">13</span><span class="cl">  
</span></span><span class="line"><span class="ln">14</span><span class="cl">  參數:
</span></span><span class="line"><span class="ln">15</span><span class="cl">  - summary: 摘要文字（可選，預設為 &#34;點擊展開&#34;）
</span></span><span class="line"><span class="ln">16</span><span class="cl">*/}}
</span></span><span class="line"><span class="ln">17</span><span class="cl"><span class="p">&lt;</span><span class="nt">details</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">18</span><span class="cl">  <span class="p">&lt;</span><span class="nt">summary</span><span class="p">&gt;</span>{{ .Get &#34;summary&#34; | default &#34;點擊展開&#34; }}<span class="p">&lt;/</span><span class="nt">summary</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">19</span><span class="cl">  {{ .Inner | markdownify }}
</span></span><span class="line"><span class="ln">20</span><span class="cl"><span class="p">&lt;/</span><span class="nt">details</span><span class="p">&gt;</span></span></span></code></pre></div></details>
<p><strong>程式碼說明</strong>：</p>
<ol>
<li><strong>註解區塊</strong>：<code>{{/* ... */}}</code> 用於說明 shortcode 的用途和使用方式</li>
<li><strong>參數獲取</strong>：<code>.Get &quot;summary&quot;</code> 獲取 summary 參數</li>
<li><strong>預設值</strong>：<code>default &quot;點擊展開&quot;</code> 提供預設文字</li>
<li><strong>內容處理</strong>：<code>.Inner</code> 獲取標籤內的內容</li>
<li><strong>Markdown 渲染</strong>：<code>markdownify</code> 將內容中的 Markdown 語法轉換為 HTML</li>
</ol>
<h3 id="步驟-2在-markdown-中使用">步驟 2：在 Markdown 中使用</h3>
<h4 id="舊方式會觸發-md033">舊方式（會觸發 MD033）</h4>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="ln"> 1</span><span class="cl"><span class="p">&lt;</span><span class="nt">details</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln"> 2</span><span class="cl"><span class="p">&lt;</span><span class="nt">summary</span><span class="p">&gt;</span>點擊查看程式碼<span class="p">&lt;/</span><span class="nt">summary</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln"> 3</span><span class="cl">
</span></span><span class="line"><span class="ln"> 4</span><span class="cl">\``<span class="sb">`toml
</span></span></span><span class="line"><span class="ln"> 5</span><span class="cl"><span class="sb">[markup]
</span></span></span><span class="line"><span class="ln"> 6</span><span class="cl"><span class="sb">  [markup.tableOfContents]
</span></span></span><span class="line"><span class="ln"> 7</span><span class="cl"><span class="sb">    startLevel = 2
</span></span></span><span class="line"><span class="ln"> 8</span><span class="cl"><span class="sb">\`</span>``
</span></span><span class="line"><span class="ln"> 9</span><span class="cl">
</span></span><span class="line"><span class="ln">10</span><span class="cl"><span class="p">&lt;/</span><span class="nt">details</span><span class="p">&gt;</span></span></span></code></pre></div><h4 id="新方式符合-markdown-規範">新方式（符合 Markdown 規範）</h4>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="ln">1</span><span class="cl">

<details>
  <summary>點擊查看程式碼</summary>
  

\```toml
[markup]
  [markup.tableOfContents]
    startLevel = 2
\```


</details></span></span></code></pre></div><h3 id="步驟-3添加-css-樣式">步驟 3：添加 CSS 樣式</h3>
<p>在 <code>layouts/partials/custom_head.html</code> 中添加樣式：</p>
<details>
  <summary>點擊查看 CSS 樣式程式碼</summary>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-css" data-lang="css"><span class="line"><span class="ln"> 1</span><span class="cl"><span class="c">/* 可折疊程式碼區塊樣式 */</span>
</span></span><span class="line"><span class="ln"> 2</span><span class="cl"><span class="nt">details</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln"> 3</span><span class="cl">  <span class="k">margin</span><span class="p">:</span> <span class="mf">1.5</span><span class="kt">rem</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="ln"> 4</span><span class="cl">  <span class="k">padding</span><span class="p">:</span> <span class="mi">1</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln"> 5</span><span class="cl">  <span class="k">background</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.05</span><span class="p">);</span>
</span></span><span class="line"><span class="ln"> 6</span><span class="cl">  <span class="k">border-radius</span><span class="p">:</span> <span class="mi">8</span><span class="kt">px</span><span class="p">;</span>
</span></span><span class="line"><span class="ln"> 7</span><span class="cl">  <span class="k">border</span><span class="p">:</span> <span class="mi">1</span><span class="kt">px</span> <span class="kc">solid</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.1</span><span class="p">);</span>
</span></span><span class="line"><span class="ln"> 8</span><span class="cl">  <span class="k">transition</span><span class="p">:</span> <span class="kc">all</span> <span class="mf">0.3</span><span class="kt">s</span> <span class="kc">ease</span><span class="p">;</span>
</span></span><span class="line"><span class="ln"> 9</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">10</span><span class="cl">
</span></span><span class="line"><span class="ln">11</span><span class="cl"><span class="nt">details</span><span class="p">:</span><span class="nd">hover</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">12</span><span class="cl">  <span class="k">background</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.08</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">13</span><span class="cl">  <span class="k">border-color</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.15</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">14</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">15</span><span class="cl">
</span></span><span class="line"><span class="ln">16</span><span class="cl"><span class="nt">details</span><span class="o">[</span><span class="nt">open</span><span class="o">]</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">17</span><span class="cl">  <span class="k">background</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.03</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">18</span><span class="cl">  <span class="k">border-color</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.2</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">19</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">20</span><span class="cl">
</span></span><span class="line"><span class="ln">21</span><span class="cl"><span class="nt">summary</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">22</span><span class="cl">  <span class="k">cursor</span><span class="p">:</span> <span class="kc">pointer</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">23</span><span class="cl">  <span class="k">font-weight</span><span class="p">:</span> <span class="mi">600</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">24</span><span class="cl">  <span class="k">font-size</span><span class="p">:</span> <span class="mf">0.95</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">25</span><span class="cl">  <span class="k">padding</span><span class="p">:</span> <span class="mf">0.5</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">26</span><span class="cl">  <span class="k">margin</span><span class="p">:</span> <span class="mi">-1</span><span class="kt">rem</span> <span class="mi">-1</span><span class="kt">rem</span> <span class="mi">0</span> <span class="mi">-1</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">27</span><span class="cl">  <span class="k">border-radius</span><span class="p">:</span> <span class="mi">8</span><span class="kt">px</span> <span class="mi">8</span><span class="kt">px</span> <span class="mi">0</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">28</span><span class="cl">  <span class="k">background</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.05</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">29</span><span class="cl">  <span class="k">transition</span><span class="p">:</span> <span class="kc">all</span> <span class="mf">0.2</span><span class="kt">s</span> <span class="kc">ease</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">30</span><span class="cl">  <span class="k">user-select</span><span class="p">:</span> <span class="kc">none</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">31</span><span class="cl">  <span class="k">list-style</span><span class="p">:</span> <span class="kc">none</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">32</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">33</span><span class="cl">
</span></span><span class="line"><span class="ln">34</span><span class="cl"><span class="nt">summary</span><span class="p">::</span><span class="nd">-webkit-details-marker</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">35</span><span class="cl">  <span class="k">display</span><span class="p">:</span> <span class="kc">none</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">36</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">37</span><span class="cl">
</span></span><span class="line"><span class="ln">38</span><span class="cl"><span class="nt">summary</span><span class="p">::</span><span class="nd">before</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">39</span><span class="cl">  <span class="k">content</span><span class="p">:</span> <span class="s1">&#39;▶&#39;</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">40</span><span class="cl">  <span class="k">display</span><span class="p">:</span> <span class="kc">inline-block</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">41</span><span class="cl">  <span class="k">margin-right</span><span class="p">:</span> <span class="mf">0.5</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">42</span><span class="cl">  <span class="k">transition</span><span class="p">:</span> <span class="k">transform</span> <span class="mf">0.3</span><span class="kt">s</span> <span class="kc">ease</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">43</span><span class="cl">  <span class="k">font-size</span><span class="p">:</span> <span class="mf">0.8</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">44</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">45</span><span class="cl">
</span></span><span class="line"><span class="ln">46</span><span class="cl"><span class="nt">details</span><span class="o">[</span><span class="nt">open</span><span class="o">]</span> <span class="nt">summary</span><span class="p">::</span><span class="nd">before</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">47</span><span class="cl">  <span class="k">transform</span><span class="p">:</span> <span class="nb">rotate</span><span class="p">(</span><span class="mi">90</span><span class="kt">deg</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">48</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">49</span><span class="cl">
</span></span><span class="line"><span class="ln">50</span><span class="cl"><span class="nt">summary</span><span class="p">:</span><span class="nd">hover</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">51</span><span class="cl">  <span class="k">background</span><span class="p">:</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.1</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">52</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">53</span><span class="cl">
</span></span><span class="line"><span class="ln">54</span><span class="cl"><span class="nt">details</span><span class="o">[</span><span class="nt">open</span><span class="o">]</span> <span class="nt">summary</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">55</span><span class="cl">  <span class="k">margin-bottom</span><span class="p">:</span> <span class="mi">1</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">56</span><span class="cl">  <span class="k">border-bottom</span><span class="p">:</span> <span class="mi">1</span><span class="kt">px</span> <span class="kc">solid</span> <span class="nb">rgba</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mi">0</span><span class="p">,</span> <span class="mf">0.1</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">57</span><span class="cl">  <span class="k">border-radius</span><span class="p">:</span> <span class="mi">8</span><span class="kt">px</span> <span class="mi">8</span><span class="kt">px</span> <span class="mi">0</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">58</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">59</span><span class="cl">
</span></span><span class="line"><span class="ln">60</span><span class="cl"><span class="c">/* 確保 details 內的程式碼區塊樣式正常 */</span>
</span></span><span class="line"><span class="ln">61</span><span class="cl"><span class="nt">details</span> <span class="nt">pre</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">62</span><span class="cl">  <span class="k">margin</span><span class="p">:</span> <span class="mi">1</span><span class="kt">rem</span> <span class="mi">0</span> <span class="mi">0</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">63</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">64</span><span class="cl">
</span></span><span class="line"><span class="ln">65</span><span class="cl"><span class="nt">details</span> <span class="o">&gt;</span> <span class="o">*</span><span class="p">:</span><span class="nd">not</span><span class="o">(</span><span class="nt">summary</span><span class="o">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">66</span><span class="cl">  <span class="k">animation</span><span class="p">:</span> <span class="n">fadeIn</span> <span class="mf">0.3</span><span class="kt">s</span> <span class="kc">ease</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">67</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">68</span><span class="cl">
</span></span><span class="line"><span class="ln">69</span><span class="cl"><span class="p">@</span><span class="k">keyframes</span> <span class="nt">fadeIn</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">70</span><span class="cl">  <span class="nt">from</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">71</span><span class="cl">    <span class="k">opacity</span><span class="p">:</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">72</span><span class="cl">    <span class="k">transform</span><span class="p">:</span> <span class="nb">translateY</span><span class="p">(</span><span class="mi">-10</span><span class="kt">px</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">73</span><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="ln">74</span><span class="cl">  <span class="nt">to</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">75</span><span class="cl">    <span class="k">opacity</span><span class="p">:</span> <span class="mi">1</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">76</span><span class="cl">    <span class="k">transform</span><span class="p">:</span> <span class="nb">translateY</span><span class="p">(</span><span class="mi">0</span><span class="p">);</span>
</span></span><span class="line"><span class="ln">77</span><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="ln">78</span><span class="cl"><span class="p">}</span>
</span></span><span class="line"><span class="ln">79</span><span class="cl">
</span></span><span class="line"><span class="ln">80</span><span class="cl"><span class="c">/* 響應式設計 */</span>
</span></span><span class="line"><span class="ln">81</span><span class="cl"><span class="p">@</span><span class="k">media</span> <span class="o">(</span><span class="nt">max-width</span><span class="o">:</span> <span class="nt">768px</span><span class="o">)</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">82</span><span class="cl">  <span class="nt">details</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">83</span><span class="cl">    <span class="k">margin</span><span class="p">:</span> <span class="mi">1</span><span class="kt">rem</span> <span class="mi">0</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">84</span><span class="cl">    <span class="k">padding</span><span class="p">:</span> <span class="mf">0.8</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">85</span><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="ln">86</span><span class="cl">
</span></span><span class="line"><span class="ln">87</span><span class="cl">  <span class="nt">summary</span> <span class="p">{</span>
</span></span><span class="line"><span class="ln">88</span><span class="cl">    <span class="k">font-size</span><span class="p">:</span> <span class="mf">0.9</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">89</span><span class="cl">    <span class="k">padding</span><span class="p">:</span> <span class="mf">0.4</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">90</span><span class="cl">    <span class="k">margin</span><span class="p">:</span> <span class="mf">-0.8</span><span class="kt">rem</span> <span class="mf">-0.8</span><span class="kt">rem</span> <span class="mi">0</span> <span class="mf">-0.8</span><span class="kt">rem</span><span class="p">;</span>
</span></span><span class="line"><span class="ln">91</span><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="ln">92</span><span class="cl"><span class="p">}</span></span></span></code></pre></div></details>
<h2 id="進階功能">進階功能</h2>
<h3 id="自定義參數">自定義參數</h3>
<p>你可以擴展 shortcode 支援更多參數：</p>
<details>
  <summary>點擊查看進階 Shortcode 程式碼</summary>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="ln"> 1</span><span class="cl">{{/*
</span></span><span class="line"><span class="ln"> 2</span><span class="cl">  進階 Details shortcode
</span></span><span class="line"><span class="ln"> 3</span><span class="cl">  
</span></span><span class="line"><span class="ln"> 4</span><span class="cl">  參數:
</span></span><span class="line"><span class="ln"> 5</span><span class="cl">  - summary: 摘要文字
</span></span><span class="line"><span class="ln"> 6</span><span class="cl">  - open: 是否預設展開（true/false）
</span></span><span class="line"><span class="ln"> 7</span><span class="cl">  - class: 自定義 CSS 類別
</span></span><span class="line"><span class="ln"> 8</span><span class="cl">*/}}
</span></span><span class="line"><span class="ln"> 9</span><span class="cl"><span class="p">&lt;</span><span class="nt">details</span> <span class="err">{{</span> <span class="na">if</span> <span class="err">.</span><span class="na">Get</span> <span class="err">&#34;</span><span class="na">open</span><span class="err">&#34;</span> <span class="err">}}</span><span class="na">open</span><span class="err">{{</span> <span class="na">end</span> <span class="err">}}</span> <span class="err">{{</span> <span class="na">with</span> <span class="err">.</span><span class="na">Get</span> <span class="err">&#34;</span><span class="na">class</span><span class="err">&#34;</span> <span class="err">}}</span><span class="na">class</span><span class="o">=</span><span class="s">&#34;{{ . }}&#34;</span><span class="err">{{</span> <span class="na">end</span> <span class="err">}}</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">10</span><span class="cl">  <span class="p">&lt;</span><span class="nt">summary</span><span class="p">&gt;</span>{{ .Get &#34;summary&#34; | default &#34;點擊展開&#34; }}<span class="p">&lt;/</span><span class="nt">summary</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="ln">11</span><span class="cl">  {{ .Inner | markdownify }}
</span></span><span class="line"><span class="ln">12</span><span class="cl"><span class="p">&lt;/</span><span class="nt">details</span><span class="p">&gt;</span></span></span></code></pre></div></details>
<p><strong>使用範例</strong>：</p>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="ln">1</span><span class="cl">

<details>
  <summary>重要提示</summary>
  
這個區塊預設是展開的

</details></span></span></code></pre></div><h3 id="巢狀使用">巢狀使用</h3>
<p>Shortcode 支援巢狀使用：</p>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown"><span class="line"><span class="ln">1</span><span class="cl">

<details>
  <summary>外層標題</summary>
  

這是外層內容



<details>
  <summary>內層標題</summary>
  
這是內層內容

</details>


</details></span></span></code></pre></div><h2 id="遷移指南">遷移指南</h2>
<h3 id="批量替換">批量替換</h3>
<p>如果你已經有很多使用 HTML 標籤的文章，可以使用以下步驟批量替換：</p>
<h4 id="步驟-1備份檔案">步驟 1：備份檔案</h4>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="ln">1</span><span class="cl">git commit -am <span class="s2">&#34;備份：準備遷移到 shortcode&#34;</span></span></span></code></pre></div><h4 id="步驟-2使用-sed-批量替換macos">步驟 2：使用 sed 批量替換（macOS）</h4>
<details>
  <summary>點擊查看批量替換腳本</summary>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="ln"> 1</span><span class="cl"><span class="c1"># 替換開始標籤</span>
</span></span><span class="line"><span class="ln"> 2</span><span class="cl">find content -name <span class="s2">&#34;*.md&#34;</span> -type f -exec sed -i <span class="s1">&#39;&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="ln"> 3</span><span class="cl"><span class="se"></span>  <span class="s1">&#39;s/&lt;details&gt;$/{{&amp;lt; details summary=&#34;點擊查看程式碼&#34; &amp;gt;}}/g&#39;</span> <span class="o">{}</span> +
</span></span><span class="line"><span class="ln"> 4</span><span class="cl">
</span></span><span class="line"><span class="ln"> 5</span><span class="cl"><span class="c1"># 替換帶 summary 的開始標籤</span>
</span></span><span class="line"><span class="ln"> 6</span><span class="cl">find content -name <span class="s2">&#34;*.md&#34;</span> -type f -exec sed -i <span class="s1">&#39;&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="ln"> 7</span><span class="cl"><span class="se"></span>  <span class="s1">&#39;s/&lt;details&gt;.*&lt;summary&gt;\(.*\)&lt;\/summary&gt;/{{&amp;lt; details summary=&#34;\1&#34; &amp;gt;}}/g&#39;</span> <span class="o">{}</span> +
</span></span><span class="line"><span class="ln"> 8</span><span class="cl">
</span></span><span class="line"><span class="ln"> 9</span><span class="cl"><span class="c1"># 替換結束標籤</span>
</span></span><span class="line"><span class="ln">10</span><span class="cl">find content -name <span class="s2">&#34;*.md&#34;</span> -type f -exec sed -i <span class="s1">&#39;&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="ln">11</span><span class="cl"><span class="se"></span>  <span class="s1">&#39;s/&lt;\/details&gt;/{{&amp;lt; \/details &amp;gt;}}/g&#39;</span> <span class="o">{}</span> +</span></span></code></pre></div></details>
<h4 id="步驟-3驗證結果">步驟 3：驗證結果</h4>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="ln">1</span><span class="cl"><span class="c1"># 檢查是否還有 HTML 標籤</span>
</span></span><span class="line"><span class="ln">2</span><span class="cl">grep -r <span class="s2">&#34;&lt;details&gt;&#34;</span> content/
</span></span><span class="line"><span class="ln">3</span><span class="cl">grep -r <span class="s2">&#34;&lt;/details&gt;&#34;</span> content/</span></span></code></pre></div><h4 id="步驟-4測試並提交">步驟 4：測試並提交</h4>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="ln">1</span><span class="cl">hugo server -D
</span></span><span class="line"><span class="ln">2</span><span class="cl"><span class="c1"># 確認無誤後提交</span>
</span></span><span class="line"><span class="ln">3</span><span class="cl">git add .
</span></span><span class="line"><span class="ln">4</span><span class="cl">git commit -m <span class="s2">&#34;遷移到 shortcode：移除 HTML 標籤&#34;</span></span></span></code></pre></div><h2 id="常見問題">常見問題</h2>
<h3 id="q1-shortcode-不生效">Q1: Shortcode 不生效？</h3>
<p><strong>可能原因</strong>：</p>
<ol>
<li>檔案路徑錯誤：確認檔案在 <code>layouts/shortcodes/</code> 目錄</li>
<li>檔案名稱錯誤：檔案名稱應該是 <code>details.html</code></li>
<li>Hugo 版本過舊：確認 Hugo 版本 &gt;= 0.55</li>
</ol>
<p><strong>解決方案</strong>：</p>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="ln">1</span><span class="cl"><span class="c1"># 檢查 Hugo 版本</span>
</span></span><span class="line"><span class="ln">2</span><span class="cl">hugo version
</span></span><span class="line"><span class="ln">3</span><span class="cl">
</span></span><span class="line"><span class="ln">4</span><span class="cl"><span class="c1"># 重新啟動 Hugo server</span>
</span></span><span class="line"><span class="ln">5</span><span class="cl">hugo server -D --disableFastRender</span></span></code></pre></div><h3 id="q2-markdown-內容沒有被渲染">Q2: Markdown 內容沒有被渲染？</h3>
<p><strong>問題</strong>：shortcode 內的 Markdown 語法沒有被轉換為 HTML</p>
<p><strong>解決方案</strong>：</p>
<p>確認使用了 <code>markdownify</code> 函數：</p>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-html" data-lang="html"><span class="line"><span class="ln">1</span><span class="cl">{{ .Inner | markdownify }}</span></span></code></pre></div><h3 id="q3-如何處理全域-gitignore-規則">Q3: 如何處理全域 gitignore 規則？</h3>
<p>如果你的專案需要追蹤 <code>.claude/settings.local.json</code>，但被全域 gitignore 排除：</p>
<h4 id="方案-1強制添加">方案 1：強制添加</h4>





<div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="ln">1</span><span class="cl">git add -f .claude/settings.local.json</span></span></code></pre></div><h4 id="方案-2在專案-gitignore-中覆蓋">方案 2：在專案 <code>.gitignore</code> 中覆蓋</h4>





<pre tabindex="0"><code class="language-gitignore" data-lang="gitignore"># 允許追蹤 .claude/settings.local.json
!.claude/settings.local.json</code></pre><h3 id="q4-css-樣式沒有生效">Q4: CSS 樣式沒有生效？</h3>
<p><strong>檢查清單</strong>：</p>
<ol>
<li>確認 CSS 是否正確載入到 <code>custom_head.html</code></li>
<li>確認瀏覽器快取是否清除（Ctrl+Shift+R 強制重新整理）</li>
<li>確認 CSS 選擇器是否正確</li>
<li>確認是否有其他 CSS 覆蓋了樣式</li>
</ol>
<h2 id="效能考量">效能考量</h2>
<h3 id="shortcode-vs-html-標籤">Shortcode vs HTML 標籤</h3>
<table>
  <thead>
      <tr>
          <th>項目</th>
          <th>HTML 標籤</th>
          <th>Shortcode</th>
      </tr>
  </thead>
  <tbody>
      <tr>
          <td>建置時間</td>
          <td>快</td>
          <td>稍慢（需處理）</td>
      </tr>
      <tr>
          <td>執行時效能</td>
          <td>相同</td>
          <td>相同</td>
      </tr>
      <tr>
          <td>快取效果</td>
          <td>相同</td>
          <td>相同</td>
      </tr>
      <tr>
          <td>維護成本</td>
          <td>高</td>
          <td>低</td>
      </tr>
  </tbody>
</table>
]]></content:encoded></item></channel></rss>