このブログで使える記法

将来の自分のためのリファレンスです。以下はすべてドキュメントからの推測ではなく、 テーマのソースコードで確認したものです。各セクションで記法とその出力を示します。

コールアウト

GitHub / Obsidian のアラート記法です。種類は NOTE、TIP、IMPORTANT、 WARNING、CAUTION の5つ。+ タイトル で見出しを指定できます。

> [!NOTE]
> Plain note.

> [!WARNING] これは注意
> タイトル付きの警告です。

{{< callout >}} ショートコードもありますが、テーマ側で上の記法を推奨する 非推奨扱いになっています。使わないこと。

Mermaid

言語に mermaid を指定したコードブロックです。スクリプトは実際に図がある ページでのみ読み込まれます。

```mermaid
sequenceDiagram
    Browser->>Pages: GET /en/blog/
    Pages-->>Browser: static HTML
    Browser->>Remark42: GET /api/v1/find
```

フローチャートも使えます:

Markmap

ネストしたリストからマインドマップを作ります。height 属性を指定できます。

```markmap {height="300px"}
- Root
  - Branch
    - Leaf
```

- Backend
  - Services
    - APIs
    - Event-driven
  - Data
    - PostgreSQL
    - MongoDB
- Infrastructure
  - AWS
    - CDK
    - CloudFormation
  - Azure
    - Terraform
- Practice
  - CI/CD
  - Observability
  - Incident response

数式

KaTeX を使います。フロントマターの math: true、math ショートコード、 またはサイト全体の設定で読み込まれます。インラインは $...$、ブロックは $$...$$。

Inline: $O(n \log n)$

$$
p_{99} = \inf\{x : F(x) \ge 0.99\}
$$

インライン: 計算量は $O(n \log n)$ です。

コード

通常のコードブロックで、Hugo 内蔵の Chroma がハイライトします。行番号はサイト 全体では無効ですが、ブロック単位で有効にできます。

```python {linenos=true, hl_lines=[2]}
def charge(rate_kw: float) -> float:
    return min(rate_kw, MAX_KW)
```

1def charge(rate_kw: float) -> float:
2    return min(rate_kw, MAX_KW)  # clamp to the connector limit

ステップ

### 見出しを囲むと、それぞれが番号付きのステップになります。

{{< steps >}}
### 最初の手順
これをします。
### 次の手順
次にこれをします。
{{< /steps >}}

折りたたみ

{{< spoiler text="クリックで展開" >}}
隠れている内容。
{{< /spoiler >}}

ボタン

{{< button url="/ja/about/" >}}プロフィール{{< /button >}}

Charts

Plotly を使います。data にはページフォルダ内の JSON ファイルを拡張子なしで 指定します。ここでは demo-chart.json がこの index.md の隣にあります。

{{< chart data="demo-chart" >}}

CSV テーブル

同じ要領で、ページフォルダ内の .csv を指定します。注意点として、パラメータは src ではなく path です。ショートコード自身のコメントには src と書かれて いますが、コードは .Get "path" を読んでいます。src を使うとビルドが nil ポインタエラーで失敗します。

{{< table path="demo-table.csv" caption="サービス別レイテンシ" >}}

通常の Markdown テーブルも使えます:

画像

通常の Markdown です。レンダーフックがまずページフォルダを探し、次に assets/media/ を探して、複数サイズのレスポンシブな srcset を出力します。

![代替テキスト](authors/me.webp)

動画と音声

{{< video src="clip.mp4" controls="yes" >}}
{{< audio src="episode.mp3" >}}

どちらもページフォルダ、assets/media/、リモート URL の順に解決します。

アイコン

{{< icon name="brands/github" >}} のように文中に置けます。

のように文中に置けます。

Jupyter ノートブック

{{< notebook path="analysis.ipynb" >}}

.ipynb をそのまま描画します。データ中心の記事に便利です。

インクルード

{{< include "snippets/shared-warning.md" >}}

別の Markdown ファイルを取り込みます。パスは content/ からの相対です。

サポートされていないもの

PlantUML。このテーマには PlantUML のレンダーフックもスクリプトも存在しません。 レイアウトと JS バンドルを確認済みです。必要になった場合の選択肢:

1. Mermaid を使う。シーケンス、フローチャート、クラス、ステート、ER、ガントを カバーしており、PlantUML の用途の大半を満たします。
2. .puml をオフラインで SVG に変換してコミットし、通常の画像として埋め込む。 ビルド時の依存も外部サーバーも不要です。

PlantUML のレンダーフック自体は layouts/_markup/render-codeblock-plantuml.html に20行ほどで書けますが、ビルド時にレンダリングサーバーを呼ぶ必要があるため、 避けたいところです。

重要なフロントマター

---
title: "記事タイトル"
summary: "一覧と meta description に表示されます。"
date: 2026-08-08
translationKey: some-key   # pt/en/ja 版を相互にリンクする
authors: [me]
tags: [meta, markdown]
math: true                 # このページで KaTeX を読み込む
commentable: true          # blog/_index.md から継承済み
draft: false
---

最も重要なのは translationKey です。これがあるおかげで言語切り替えがトップ ページではなく同じ記事に移動します。