Blowfish（Hugoテーマ）のショートコード使い方まとめ

参照元は nunocoracao/blowfish の exampleSite ドキュメントと 公式サイトのshortcodesページ（2026年7月確認）。

ox-hugoでタングル/エクスポートする前提なので、ショートコードを書く部分は全部 #+begin_export hugo 〜 #+end_export で囲んである。org地の文（説明・表）はそのままMarkdownとして出力されるので、export ブロックは不要。

org-mode的には「構文そのものを文字として見せたいexportブロック」と「実際にHugoに変換させて機能させるexportブロック」は区別が必要である。=#+begin_export hugo= はox-hugoに素通しされて実際にレンダリングされてしまうので、構文自体を文字として見せたい場合は #+begin_example=（または =#+begin_src org=）で一段リテラル化してから、その直後に本物の =#+begin_export hugo ブロックを続ける、という2段構成にしている。

ただし #+begin_example で囲んだだけでは不十分だった。Hugoのショートコード展開は、囲んでいるのがMarkdownのコードフェンスかどうかを見ずに、ファイル全体のテキストから波括弧2つのショートコード記法を機械的に探して実行してしまうため、コードブロックの中に書いた例文もそのまま実行されてビルドエラーや取得失敗の原因になる。これを防ぐには、Hugo公式のショートコードのエスケープ記法を使う必要がある。開き括弧の直後と閉じ括弧の直前に「/* 」「 */」を挟むと、実行されずに文字通りの文字列としてそのまま出力される。以下すべての節の「書き方はこう」の例では、この記法で統一した。

Alert（警告・注意喚起ボックス）

#

記事内に目立つメッセージボックスを表示する。中身は Markdown 記法。

書き方はこうなる。

#+begin_export hugo
{{< alert >}}
**Warning!** This action is destructive!
{{< /alert >}}
#+end_export

実際にレンダリングすると、こう表示される。

アイコン付き・色指定もできる。

#+begin_export hugo
{{< alert icon="fire" cardColor="#e63946" iconColor="#1d3557" textColor="#f1faee" >}}
This is an error!
{{< /alert >}}
#+end_export

Admonition（GitHub/Obsidian 風コールアウト）

#

これはショートコードではなく Hugo の render hook 経由のMarkdown拡張構文。=#+begin_export hugo= で囲む必要はなく、そのままorg内でblockquote記法として書ける（ただしox-hugo側でblockquoteへの変換確認が必要。確実に反映したい場合はexportブロック推奨）。

書き方はこう。

#+begin_export hugo
> [!TIP]
> A Tip type admonition.

> [!TIP]+ Custom Title + Custom Icon
> A collapsible admonition with custom title.
{icon="twitter"}
#+end_export

実際にレンダリングすると、こう表示される。

対応タイプはGitHub系（NOTE / TIP / IMPORTANT / WARNING / CAUTION）とObsidian系（note / abstract / info / todo / tip / success / question / warning / failure / danger / bug / example / quote）。=+=/=-= で折りたたみ制御もできる（Obsidian互換）。

Accordion（アコーディオン／折りたたみパネル）

#

書き方はこう。

#+begin_export hugo
{{< accordion mode="open" separated=true >}}
  {{< accordionItem title="Markdown example" icon="code" open=true >}}
  本文（Markdown）
  {{< /accordionItem >}}

  {{< accordionItem title="Shortcode example" md=false >}}
  {{< alert >}}インラインアラート{{< /alert >}}
  {{< /accordionItem >}}
{{< /accordion >}}
#+end_export

実際にレンダリングすると、こう表示される。

Ansible Galaxy Card

#

書き方はこう。

#+begin_export hugo
{{< ansible role="geerlingguy.docker" >}}
{{< ansible collection="community.general" >}}
#+end_export

実際にレンダリングすると、こう表示される。

role または collection のどちらか一方を指定する（ビルド時に resources.GetRemote で取得、ブラウザ側では更新されない）。

Article（記事埋め込み）

#

書き方はこう。

#+begin_export hugo
{{< article link="/docs/welcome/" showSummary=true compactSummary=true >}}
#+end_export

実際にレンダリングすると、こう表示される。

サブフォルダ運用時はパスを含めて指定する必要がある。

Badge

#

書き方はこう。

#+begin_export hugo
{{< badge >}}
New article!
{{< /badge >}}
#+end_export

実際にレンダリングすると、こう表示される。

Button

#

書き方はこう。=pageRef= は存在する内部ページのパスを指定する必要があるので、ここでは記法例として docs/getting-started を挙げているが、実際に使う際はサイト内の実在パスに置き換えること（存在しないパスを pageRef に渡すとビルド時に REF_NOT_FOUND エラーになりビルド自体が止まる）。

#+begin_export hugo
{{< button href="#button" target="_self" >}}
Call to action
{{< /button >}}

{{< button pageRef="docs/getting-started" >}}
Get started
{{< /button >}}
#+end_export

href 版（任意URL/アンカー）はそのままレンダリングできる。

pageRef=（内部ページ参照）と =href=（任意URL）が併用時は =pageRef 優先。=target=/=rel= も指定できる。

Carousel（画像カルーセル）

#

書き方はこう。=captions= の中の *formatting* もMarkdown記法（斜体）である点に注意。

#+begin_export hugo
{{< carousel images="gallery/*" aspectRatio="21-9" interval="2500" >}}

{{< carousel images="gallery/*" captions="{01.jpg:First image with *formatting*,02.jpg:Second image}" >}}
#+end_export

実際にレンダリングすると、こう表示される。

Previous Next

Previous Next

Chart（Chart.js グラフ）

#

書き方はこう。

#+begin_export hugo
{{< chart >}}
type: 'bar',
data: {
  labels: ['Tomato', 'Blueberry', 'Banana'],
  datasets: [{ label: '# of votes', data: [12, 19, 3] }]
}
{{< /chart >}}
#+end_export

実際にレンダリングすると、こう表示される。

Chart.jsの設定をそのまま記述する。

Code Importer（外部コード取り込み）

#

書き方はこう。=url= は実在するファイルのraw URLを指定する必要があり、ここでのURLは記法説明用のプレースホルダーなので実レンダリングはしていない（プレースホルダーのままビルドすると unable to fetch の警告が出る）。

#+begin_export hugo
{{< codeimporter url="https://raw.githubusercontent.com/.../mdimporter.html" type="go" startLine="11" endLine="18" >}}
#+end_export

Codeberg / Forgejo / Gitea / GitHub / GitLab Card（外部リポジトリカード）

#

書き方はこう。

#+begin_export hugo
{{< codeberg repo="forgejo/forgejo" >}}
{{< forgejo server="https://v11.next.forgejo.org" repo="a/mastodon" >}}
{{< gitea server="https://git.fsfe.org" repo="FSFE/fsfe-website" >}}
{{< github repo="nunocoracao/blowfish" showThumbnail=true >}}
{{< gitlab projectID="278964" >}}
#+end_export

実際にレンダリングすると、こう表示される。

nunocoracao/blowfish

Personal Website & Blog Theme for Hugo

HTML

2560

661

各サービスAPIからスター数・フォーク数等をリアルタイム取得表示する。=github= のみ showThumbnail がある。=gitlab= は baseURL でセルフホスト対応。

Email（難読化メールリンク）

#

書き方はこう。

#+begin_export hugo
{{< email email="mailto:[email protected]" text="text" subject="Reply to awesome article" >}}
#+end_export

実際にレンダリングすると、こう表示される。

Figure（画像・図表）

#

書き方はこう。

#+begin_export hugo
{{< figure
    src="abstract.jpg"
    alt="Abstract purple artwork"
    caption="Photo by [Jr Korpa](https://unsplash.com/@jrkorpa)"
>}}
#+end_export

実際にレンダリングすると、こう表示される。

標準Markdown画像記法でも自動変換されるので、org中では通常の [[file:image.jpg]] リンクをox-hugoが変換する形でも良い。細かい制御（caption/class/nozoom等）が必要な場合だけexportブロックで明示する。

Gallery（画像ギャラリー）

#

書き方はこう。

#+begin_export hugo
{{< gallery >}}
  <img src="gallery/01.jpg" class="grid-w33" />
  <img src="gallery/02.jpg" class="grid-w50 md:grid-w33 xl:grid-w25" />
{{< /gallery >}}
#+end_export

実際にレンダリングすると、こう表示される。

class“grid-wXX”=（10%〜100%、5%刻み。33%/66%も可）でカラム幅を指定する。

Gist（GitHub Gist埋め込み）

#

書き方はこう。

#+begin_export hugo
{{< gist "octocat" "6cad326836d38bd3a7ae" >}}
{{< gist "rauchg" "2052694" "README.md" >}}
#+end_export

実際にレンダリングすると、こう表示される。

引数は [0] GitHubユーザー名 / [1] Gist ID / [2] 任意、Gist内の特定ファイル名。

Hugging Face Card

#

書き方はこう。

#+begin_export hugo
{{< huggingface model="google-bert/bert-base-uncased" >}}
{{< huggingface dataset="stanfordnlp/imdb" >}}
#+end_export

実際にレンダリングすると、こう表示される。

model か dataset のどちらか一方を指定する。

Icon（SVGアイコン）

#

書き方はこう。

#+begin_export hugo
{{< icon "github" >}}
#+end_export

実際にレンダリングすると、こう表示される。

独自アイコンは assets/icons/ にSVG配置し、拡張子なしファイル名で参照できる。

KaTeX（数式）

#

書き方はこう。

#+begin_export hugo
{{< katex >}}
\(f(a,b,c) = (a^2+b^2+c^2)^3\)
#+end_export

実際にレンダリングすると、こう表示される。

\(f(a,b,c) = (a^2+b^2+c^2)^3\)

記事内に1回だけ配置すればページ内の数式が自動レンダリングされる。org自体のLaTeX記法（=\( \)=）と併用する場合はexportブロック内でエスケープが崩れないか要確認。

Keyword / KeywordList（キーワード強調）

#

書き方はこう。

#+begin_export hugo
{{< keyword >}} *Super* skill {{< /keyword >}}

{{< keywordList >}}
{{< keyword icon="github" >}} Lorem ipsum dolor. {{< /keyword >}}
{{< keyword icon="code" >}} **Important** skill {{< /keyword >}}
{{< /keywordList >}}
#+end_export

実際にレンダリングすると、こう表示される。=*Super*=（斜体1個）と =**Important**=（太字2個）が使い分けられている点に注目。

Lead（リード文強調）

#

書き方はこう。

#+begin_export hugo
{{< lead >}}
When life gives you lemons, make lemonade.
{{< /lead >}}
#+end_export

実際にレンダリングすると、こう表示される。

List（記事一覧表示）

#

書き方はこう。

#+begin_export hugo
{{< list limit=2 >}}
{{< list title="Samples" cardView=true limit=6 where="Type" value="sample" >}}
#+end_export

実際にレンダリングすると、こう表示される。

Recent

カバー画像を直したら、また別の穴が3つ出てきた話

26 July 2026·136 words·1 min

Hugo Git Hugo Ox-Hugo Emacs

Samples

LTR/RTL

#

書き方はこう。

#+begin_export hugo
- This is a markdown list.
{{% rtl %}}
- هذه القائمة باللغة العربية
{{% /rtl %}}
#+end_export

実際にレンダリングすると、こう表示される。

• This is a markdown list.

Markdown Importer（外部Markdown取り込み）

#

書き方はこう。こちらも url は記法説明用のプレースホルダーなので、実在するraw URLに置き換えるまでは実レンダリングしない。

#+begin_export hugo
{{< mdimporter url="https://raw.githubusercontent.com/.../README.md" >}}
#+end_export

Mermaid（図表・ダイアグラム）

#

書き方はこう。

#+begin_export hugo
{{< mermaid >}}
graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit]
{{< /mermaid >}}
#+end_export

実際にレンダリングすると、こう表示される。

graph LR;
A[Lemons]-->B[Lemonade];
B-->C[Profit]

org標準の #+begin_src mermaid ブロックとは別物である点に注意（Hugo側でレンダリングさせたい場合はexport hugoブロックを使う）。

Swatches（カラーパレット表示）

#

書き方はこう。

#+begin_export hugo
{{< swatches "#64748b" "#3b82f6" "#06b6d4" >}}
#+end_export

実際にレンダリングすると、こう表示される。

Tabs（タブ切り替え）

#

書き方はこう。

#+begin_export hugo
{{< tabs group="lang" default="Python" >}}
    {{< tab label="JavaScript" icon="code" >}}
    ```javascript
    console.log("Hello");
    ```
    {{< /tab >}}
    {{< tab label="Python" icon="sun" >}}
    ```python
    print("Hello")
    ```
    {{< /tab >}}
{{< /tabs >}}
#+end_export

実際にレンダリングすると、こう表示される。

console.log("Hello");

print("Hello")

Timeline（タイムライン）

#

書き方はこう。

#+begin_export hugo
{{< timeline >}}
{{< timelineItem icon="github" header="header" badge="badge test" subheader="subheader" >}}
本文
{{< /timelineItem >}}
{{< /timeline >}}
#+end_export

実際にレンダリングすると、こう表示される。

1. header

   badge test

   subheader

   本文

TypeIt（タイプライター演出）

#

書き方はこう。

#+begin_export hugo
{{< typeit
  tag=h3
  speed=50
  breakLines=false
  loop=true
>}}
"Frankly, my dear, I don't give a damn."
{{< /typeit >}}
#+end_export

実際にレンダリングすると、こう表示される。

Video（動画埋め込み）

#

書き方はこう。=caption= の中の **説明文** もMarkdown記法（太字）である点に注意。

#+begin_export hugo
{{< video
    src="https://example.com/video.webm"
    poster="https://example.com/poster.jpg"
    caption="**説明文**"
    loop=true
    muted=true
>}}
#+end_export

実際にレンダリングすると、こう表示される。

Youtube Lite（YouTube軽量埋め込み）

#

書き方はこう。

#+begin_export hugo
{{< youtubeLite id="SgXhGb-7QbU" label="Blowfish-tools demo" params="start=130&end=10&controls=0" >}}
#+end_export

実際にレンダリングすると、こう表示される。

補足（org運用時の注意点）

#

#+begin_export hugo ... #+end_export の中身は ox-hugo によって 無変換のまま素通し される。org内の *bold* や /italic/ のようなorg記法は効かないので、ショートコード内で強調したい場合はMarkdownの **bold** / *italic* をそのまま書く（この記事もその方針で統一している）。

all-posts.org のようにファイル内に複数記事が * 見出し で区切られている場合、ox-hugoの #+hugo_base_dir や各見出しの :EXPORT_FILE_NAME: プロパティ設定が別途必要になる。

既存記事に貼り付ける際は、export blockの直前直後に空行を入れないとorg側のパース崩れが起きるケースがあるので注意する。

Admonitionだけはショートコードではなく render-blockquote.html によるMarkdown render hook実装である。

「構文そのものを文字として見せたい」場合は、=#+begin_export hugo= をそのまま書くのではなく #+begin_example=（または =#+begin_src org=）で一段リテラル化してから、その直後に本物の =#+begin_export hugo ブロックを続けて実際のレンダリング結果も見せる、という2段構成にしておくと分かりやすい。

ただし #+begin_example で囲むだけでは足りない。Hugoのショートコード展開はMarkdownのコードフェンスの中かどうかを見ずに、ファイル全体から波括弧2つのショートコード記法を探して実行してしまうため、例文として書いたつもりの pageRef や外部URL指定がそのまま実行されて REF_NOT_FOUND やfetch失敗の原因になることがある。=#+begin_example= の中に書くショートコード例は、開き括弧の直後と閉じ括弧の直前に「/* 」「 */」を挟むエスケープ記法（Hugo公式）で書いておく必要がある。