MDX スタイルガイド

記事を書くときのために、このサイトがサポートしている MDX 記法をまとめました。 書き方に迷ったらここを見る、新しいコンポーネントはここで試す — そんな場所です。

見出しと本文

見出しは h2 と h3 の 2 段構成です。 サイドバーの目次はこの見出し構造から自動生成され、見出し自体もアンカーリンクになっています。 クリックすれば、その章・節への直リンクを共有できます。

本文では 強調、イタリック、打ち消し線、インラインコード が使えます。 行間や文字サイズは、日本語の長文が読みやすいように調整しています。

リストとテーブル

リスト・タスクリスト・テーブルは GFM (GitHub Flavored Markdown) をそのまま使えます。 Velite が remark-gfm を内蔵しているため、追加の設定は不要です。

1. 番号付きリスト
2. 二番目の項目
   • ネストした箇条書き

• 完了したタスク
• 未完了のタスク

コードブロック

コードブロックは Shiki によってシンタックスハイライトされます。

type Post = {
  title: string
  emoji: string
  tags: string[]
}
 
export function sortByDate(posts: Post[], order: "asc" | "desc" = "desc") {
  return [...posts].sort((a, b) =>
    order === "desc" ? b.date.localeCompare(a.date) : a.date.localeCompare(b.date),
  )
}

pnpm dev        # 開発プレビュー
pnpm preview    # 本番プレビュー (検索・API も動く)

ファイル名と行ハイライト

フェンスに title と {行番号} を指定すると、ファイル名ラベルと行ハイライトが表示されます。

const posts = defineCollection({
	pattern: "posts/*/index.mdx",
});

図 (mermaid)

図は ```mermaid フェンスで書きます。ビルド時に SVG へ変換され、テーマに追従してライト版・ダーク版が切り替わります。

width で最大幅を指定できます:

引用とリンク

引用には左側にボーダーが付きます。 出典の提示や、自分の文章と区別したいときに使えます。

リンクは通常の Markdown 記法で書くだけです。 内部リンク はプリフェッチ付きのソフトナビゲーションに、外部リンク (example.com) は「新規タブで開く + 外部リンクアイコン」になります。 リンク先ごとの書き分けを意識する必要はありません。

区切り線

コールアウト

補足や注意事項を目立たせるためのボックスです。 Info Tip Warn Danger の 4 種類があり、title で見出しを変更できます。

キー表示

ショートカットは Cmd+Shift+P のようにインラインで書けます。 文中にそのまま書けるので、空行は不要です。

手順リスト

順序のある作業には Steps を使います。

1. 依存をインストール

   まず必要なパッケージを追加します。

   pnpm add -D wrangler

2. 設定ファイルを書く

   wrangler.jsonc にバインディングを追記します。 手順内の本文も、検索や関連記事計算の対象になります。

3. デプロイ

   最後にデプロイして完了です。

ファイルツリー

ディレクトリ構成は FileTree に Markdown の箇条書きを書くだけです。 子要素を持つ項目は自動的にフォルダーアイコンになります。

折りたたみ

長いログや余談は Details で折りたためます。 折りたたまれた内容も検索と関連記事計算の対象です。

[related] all 26 embeddings cached
[related] wrote src/generated/related.json

画像

画像は <Img> コンポーネントで表示します。 記事フォルダーに画像ファイルを配置し、相対パスで参照する方式です。

✕

ビルド時に画像サイズを取得して width / height 属性を付与するため、読み込み中にレイアウトシフトが起きません。 クリックするとライトボックスで拡大表示されますが、これはネイティブの dialog 要素です。

幅指定とキャプションにも対応しています。 キャプションも、コールアウトと同様に前後を空行で囲んで書きます。

✕

なお、記法を統一するために Markdown 記法の ![]() はビルドエラーにしています。alt 属性の書き忘れも同様です。

ただし、生 JSX の <img> だけはガードできないため、規約として使わないように。

記事カード

内部記事へのリンクは LinkCard でカード表示できます。 デモとして、この記事自身のカードを配置しています。

存在しない slug を書くとビルドエラーになるので、リンク切れのカードが公開されることはありません。

外部リンクカード

外部サイトへのリンクは OgpCard を使います。 OGP メタデータはビルド時に取得・キャッシュするため、閲覧時にメタデータ取得は発生しません (画像のみ配信元から直接読み込みます)。

Markdown for the component era | MDXMDX lets you use JSX in your markdown content. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing long-form content with components a blast.mdxjs.com

og:image や description を持たないサイトは、2 枚目 (example.com) のようにタイトルとホスト名だけの表示になります。 取得に失敗した場合も同様のプレーンカードにフォールバックされます。

おわりに

以上が、このサイトでサポートしている MDX 記法です。

各コンポーネントの実装方針や、このサイト全体の仕組みはこちらの記事にまとめています。