Day 25. Hugo Shortcode 其他運用

12th鐵人賽 hugo

littlebookboy

2020-10-08 12:39:19

2229 瀏覽

分享至

前言

本篇會介紹幾種使用 Shortcode 引入到 Markdown，以達成各種目的。

Code Block

Markdown 寫法

使用 Markdown 語法插入程式區塊的方式如下 (這只是多種格式的其中一種)：

```
# put codes here...
```

可以看到 Markdown 用法很單純，使用 ``` 上下包住程式即可，方便在寫文過程直接使用，但若是我們想要讓他「顯示行號」、「標示檔名、語言」，甚至是支援「頁籤切換」，或許已經有現成的外掛，或是不同的 Markdwon 驅動可以做到，不過若使用 Shortcode 搭配，就可以統一用法，也免去可能需要多一道自行整合的手續。

Tranquilpeak Shortcode - codeblock

這邊要介紹佈景 Tranquilpeak 提供的 Shortcode - codeblock.html，其原始碼如下：

{{ if .IsNamedParams }}
  {{ $.Scratch.Add "c-title" (.Get "title") }}
  {{ $.Scratch.Add "c-language" (lower (.Get "lang")) }}
  {{ $.Scratch.Add "c-url" (.Get "url") }}
  {{ $.Scratch.Add "c-link-text" (.Get "link-text") }}
{{ else }}
  {{ if ge (len .Params) 1 }}
    {{ $.Scratch.Add "c-title" (.Get 0) }}
  {{ end }}
  {{ if ge (len .Params) 2 }}
    {{ $.Scratch.Add "c-language" (lower (.Get 1)) }}
  {{ end }}
  {{ if ge (len .Params) 3 }}
    {{ $.Scratch.Add "c-url" (.Get 2) }}
  {{ end }}
  {{ if ge (len .Params) 4 }}
    {{ $.Scratch.Add "c-link-text" (.Get 3) }}
  {{ end }}
{{ end }}
{{ $trimmedContent := trim .Inner "\n" }}
<figure class="highlight {{ $.Scratch.Get "c-language" }} language-{{ with ($.Scratch.Get "c-language") }}{{ . }}{{ end }}">
  <figcaption>
    {{ if and ($.Scratch.Get "c-url") ($.Scratch.Get "c-title") }}
      <span>{{ $.Scratch.Get "c-title" }}</span><a href="{{ ($.Scratch.Get "c-url") | safeURL }}" target="_blank" rel="external">{{ $.Scratch.Get "c-link-text" | default ($.Scratch.Get "c-title") }}</a>
    {{ else if $.Scratch.Get "c-title" }}
      <span>{{ $.Scratch.Get "c-title" }}</span>
    {{ end }}
  </figcaption>
  <table>
    <tbody>
      <tr>
        <td class="gutter">
          <pre>{{ range $index,$value := (split $trimmedContent "\n") }}<span class="line">{{ add $index 1 }}</span><br>{{ end }}</pre>
        </td>
        <td class="code">
          <pre class="code-highlight language-{{ $.Scratch.Get "c-language" }}"><code class="{{ $.Scratch.Get "c-language" }}">{{ $trimmedContent }}</code></pre>
        </td>
      </tr>
    </tbody>
  </table>
</figure>

前面 if .IsNamedParams ... else 這一大段，是為了「設置參數」：

如果有任何被指名的參數 (例如 {{< foo title="" >}}，這邊就有一個被指名的參數為 title)，進入 if，否則進入 else
進入 if 之後，連續幾行 $.Scratch.Add 是在「創建變數」，之後就可以透過 $.Scratch.Get 取得：
- 如果有給 title，創建變數 c-title，讓 c-title = title 值
- 如果有給 lang，創建變數 c-language，讓 c-language = lang 值
- 如果有給 url，創建變數 c-url，讓 c-url = url 值
- 如果有給 link-text，創建變數 c-link-text，讓 c-link-text = link-text 值
else 中設置語法與 if 是一樣的意思，只是判斷方式由「是否給定對應名稱的參數」，改為「是否有照定義的順序傳入參數」：
- if ge (len .Params) 1 是指呼叫 shortcode 的語法有帶參數，例如 {{< foo param1 param2 >}} 這樣，透過 ge 方法判斷若 .Params 這包有 1 個參數，則指定給 c-title
- 也就是說，若不指定參數名稱，而是用按照順序的方式傳入，你無法不給 title 就直接給 lang：

{{< codeblock [title] [lang:language] [url] [link text] >}}
    code snippet
{{< /codeblock >}}

後續的 <figure> 區塊，配合參數設置與 HTML 語法，呈現出對應的 codeblock，以下為引入使用的範例：

---
title: "測試 Tranquilpeak Codeblock"
date: 2020-10-08T11:50:57+08:00
draft: true
---

## Markdown 語法

｀｀｀php # 這邊用全形符號避免被解析成真的程式區塊
<?php
  echo 'Hello, Mom, I am here.';
?>
｀｀｀# 這邊用全形符號避免被解析成真的程式區塊

## Shortcode Codeblock

{{< codeblock title="test.php" lang="php" url="http://localhost" link-text="test.php">}}
<?php
  echo 'Hello, Mom, I am here.';
?>
{{< /codeblock >}}

成效：

另外該佈景還有提供 Tabbed code block 頁籤樣式的程式區塊，有興趣的人也可以使用看看。

嵌入外部影片、工具區塊

網站內容有時會需要嵌入一些社群媒體的工具，例如 youtube、intagram，或是程式相關的 gist、jsfiddle、codepen 等，以下介紹幾種 Hugo Built-in 的 Shortcode，以及如何自己創建一個類似的 Shortcode。

Youtube (Hugo Built-in)

{{< youtube qtIqKaDlqXo >}}

後面那串 ID 的取得方式，可到 youtube 選擇想嵌入的影片，擷取網址後面 watch?v=qtIqKaDlqXo 位於 v= 之後的這段，塞入 Shortcode 語法中即可：

GitHub Gist (Hugo Built-in)

{{< gist littlebookboy ceaa91553e2dd3e7ee94694bc5999e43 >}}

第一個參數是你的 GitHub 帳號，第二個參數為你的 public gist 網址後面那串文字，根據上面的例子，原本網址是長這樣：

https://gist.github.com/littlebookboy/ceaa91553e2dd3e7ee94694bc5999e43

成效：

jsfiddle (Tranquilpeak)

原網址：

https://jsfiddle.net/littlebookboy/q5gLww88/

引入方式 (ID 擷取方式請參考 youtube 那段說明)：

{{< jsfiddle q5gLww88 >}}

Shortcode：

<iframe scrolling="no" width="100%" height="300" src="//jsfiddle.net/{{ .Get 0 }}/embedded/js,resources,html,css,result/light" frameborder="0" allowfullscreen=""></iframe>

成效：

CodePen

仿照 jsfiddle 做一個 CodePen 的 Shortcode：

原網址：

https://codepen.io/littlebookboy/pen/JryVMP

引入方式 (ID 擷取方式請參考 youtube 那段說明)：

{{< codepen littlebookboy JryVMP >}}

Shortcode：

<iframe height="458" style="width: 100%;" scrolling="no" title="Draft Countdown" src="https://codepen.io/{{ .Get 0 }}/embed/{{ .Get 1 }}?height=458&theme-id=light&default-tab=js,result" frameborder="no" loading="lazy" allowtransparency="true" allowfullscreen="true">
    See the Pen <a href='https://codepen.io/{{ .Get 0 }}/pen/{{ .Get 1 }}'>Draft Countdown</a> by {{ .Get 0 }}
    (<a href='https://codepen.io/{{ .Get 0 }}'>@{{ .Get 0 }}</a>) on <a href='https://codepen.io'>CodePen</a>.
  </iframe>

成效：