VuePress の Markdown 拡張メモ — Component / Slots / frontmatter（2021 アーカイブ）

2026 追記: 旧 VuePress ブログから移植した記事。VuePress 1.x は新規構築の選択肢ではなくなったため、本文は「2021 年時点の Markdown 拡張メモ」として archive する目的で残す。Container や frontmatter の発想は MDX + Astro / Next.js にも引き継がれているので、比較資料として読んでもらえれば。

2021 年当時、Aulvem の前身ブログは VuePress 1.x で組んでいた。素の Markdown だけでは目次・補足ブロック・記事メタを扱いきれず、VuePress 独自の Markdown 拡張に何度か触ることになった。この記事はそのときの設定メモを、2026 年の視点で整理し直したもの。

VuePress 1 系は 2026 年現在ほぼメンテが止まっており（要出典: 公式リポジトリで現行ステータスを要確認）、新規プロジェクトでの採用は勧めない。それでも Container や Component 埋め込みの考え方は MDX 系に引き継がれているので、当時の決め方を残しておく価値はある。

短い答え — VuePress の Markdown 拡張は3層に分けて考える

短い答え: VuePress 1.x の Markdown 拡張は「Vue Component 埋め込み」「名前付き Container（カスタムブロック）」「frontmatter」の3層に分けて捉えると整理しやすい。

理由は、それぞれの層で関わる設定ファイルと責務が違うから。Component は .vue ファイル側、Container は index.js のプラグイン設定とスタイル、frontmatter は記事メタとテンプレート側、と分けて考えると settings を見失わずに済む。

例として、繰り返し使う目次やフッターは Component、補足ボックスは Container、記事タイトル・カテゴリ・タグは frontmatter で表現する、という配分になる。

注意: 2026 年現在は MDX + フレームワーク（Astro / Next.js）が同じ役割をもっと素直に扱えるため、ここから先は「当時の VuePress 1.x ではこうだった」という archive として読んでほしい。

extendMarkdown — markdown-it の挙動を上書きする入口

短い答え: config.js の markdown.extendMarkdown で markdown-it インスタンスを直接いじれる。

VuePress 1.x は内部で markdown-it を使って Markdown をパースしており、extendMarkdown はその設定を上書きするためのフック。改行の扱い、リンクの target、シンタックスハイライト周りなどをここで調整した。

実際に使っていた設定は次のもの。エディタで改行した位置を <br> に変換する breaks: true を有効にしている。

markdown: {
  extendMarkdown: md => {
    md.set({ breaks: true })
  }
},

注意: breaks: true は1文ごとに改行する日本語ブログでは便利だが、英文段落をひとかたまりに書く運用とは相性が悪い。記事の書き方に合わせて選ぶ設定で、デフォルトでオンにすべきものではない。

Markdown 中に Vue Component を埋め込む

短い答え: VuePress では Markdown ファイルの中に Vue Component をそのまま書ける。

理由は、VuePress のビルドが Markdown を一度 Vue SFC に変換してからレンダリングしているため。.vue ファイル内と同じ記法でタグを書けば、ビルド時にコンポーネントとして解決される。

<Component名 />

繰り返し使うブロック（記事下の関連リンク、フッター、目次など）はこの方法で Component 化していた。

注意: Markdown と JSX 的な構文が同居するので、書き手側の前提知識が増える。読み手が編集者だけ・運用が小規模、というケースで効く設計で、外部ライターにも書いてもらうなら向かない。MDX も同じトレードオフを持つ。

名前付き Container でカスタムブロックを作る

短い答え: ::: type タイトル 〜 ::: 記法で、独自スタイルのブロックを定義できる。

VuePress 1.x はデフォルトで tip / warning / danger の3種類を持っており、index.js の container プラグイン設定で type を増やせる。中身は通常の Markdown として書ける。

書き方は次の通り。

::: 表示タイプ タイトル名
中はMarkdown形式で記述出来ます。
::: 

これを書くと、type 名に応じた CSS が当たるブロックとしてレンダリングされる。例:

タイトル名

中はMarkdown形式で記述出来ます。

表示タイプは index.js のプラグイン設定で定義する。type が表示タイプ名、defaultTitle がタイトル未指定時のラベル、'/' キーは言語ごとに切り替えるための prefix（当サイトは日本語デフォルトなので / のままで動く）。

src   
└─ .vuepress
   └─ theme
      └─ index.js

module.exports = (options, ctx) => {
  return {
    plugins: [
      ['container', {
        type: 'type名',
        defaultTitle: {
          '/': 'デフォルトタイトル名',
        }
      }],
    ]
  }
}

スタイル定義は custom-blocks.styl 側に置いていた。tip / warning / danger の隣に、追加した type 名のセレクタを書き足す形。

src   
└─ .vuepress
   └─ theme
      └─ styles
         └─ custom-blocks.styl

  &.tip
  &.warning
  &.danger

注意: Container は markdown-it-container プラグインの仕組みであり、Markdown 寄りの軽量な拡張。JSX 的に任意のコンポーネントを呼び出したいなら、Component 埋め込みか MDX 側に倒すほうが向く。

frontmatter — 記事メタを Markdown の先頭に置く

短い答え: YAML 形式の frontmatter で、記事のタイトル・公開日・カテゴリ・タグ・画像などを定義する。

VuePress 側のテンプレートと plugin-blog の frontmatters 設定が、ここで宣言した値を読み取り、一覧ページや個別ページにメタを反映する。当時使っていた frontmatter は次のような形。

title: 【使い方】VuePress/plugin-blogを使用してブログを自作｜Markdown編
date: 2021-03-02
category:
  - skill
tag: 
  - VuePress
image: {{Path}}
location: japan 

tag は plugin-blog の frontmatters に登録した名前を入れると、$tag や $currentTag に集計されて一覧に出る。category は登録なしで使えるが、内部の分類用に手で揃えていた。image は OG 画像兼サムネ。

注意: frontmatter のキー名はフレームワークごとに違う。VuePress 1.x は date / tag / category（単数形）だったが、Aulvem 現行（Astro）は pubDate / tags / category で揃えており、移植時にここでつまずきやすい。

Markdown 系フォーマット比較（2026 年視点）

VuePress 1.x の Container や Component 埋め込みは「Markdown を JSX 寄りに拡張する」発想の先駆けで、MDX が今ほぼ同じ役割を担っている（要出典: MDX の歴史的な位置付けは公式仕様で要確認）。

よくある質問

Q. VuePress の Markdown と普通の Markdown は何が違うか？ A. VuePress は markdown-it ベースの Markdown に、Vue Component の埋め込み・名前付き Container（::: tip など）・frontmatter・PrismJS によるコードハイライトを追加した拡張版を出力する。素の Markdown より表現力は高いが、ビルド時に Vue ランタイムが前提になる点が違う。

Q. VuePress の Container（::: tip など）と MDX のコンポーネントの違いは？ A. Container は markdown-it-container プラグインで実装された記法で、Markdown 寄りの軽量な拡張。MDX は Markdown の中に JSX をそのまま書ける別仕様で、任意の React / Vue コンポーネントを式として埋め込める。Container はカスタムブロック、MDX は完全な JSX、と責務の広さが違う。

Q. 2026 年に VuePress 1.x を新規採用する意味はあるか？ A. ほとんどない。VuePress 1 系はメンテが実質止まっており、Vue 系で続けるなら VitePress、汎用なら Astro や Next.js + MDX のほうが情報量も拡張性も多い（要出典）。既存サイトの保守目的でのみ残す形が現実的。

Q. extendMarkdown の breaks: true は必要か？ A. 好みによる。エディタで改行したところを <br> に変換する設定で、日本語ブログのように1文ごとに改行する書き方では便利。一方で英文のように段落をひとかたまりに書く場合は不要で、むしろ意図しない改行が増える原因になる。

2026 年に同じことをやるなら何を選ぶか

短い答え: Vue を残したいなら VitePress、フレームワーク非依存で書きたいなら Astro + content collections + MDX が近い体験になる。

理由は、VuePress 1 系がメンテほぼ停止である一方、VitePress は VuePress の後継として Vue チームが整理した形で、Astro は Markdown / MDX をネイティブに扱えるよう設計されているため。Aulvem は最終的に Astro に移行している。

注意: 2026 年時点での各ツールの正確な状態（最新版、メンテ体制、デフォルト機能）は公式ドキュメント側で確認してほしい（要出典）。本記事はあくまで「2021 年に VuePress 1.x で書いた人が、後から振り返って整理した」観点のメモであり、現行ツール選定のリファレンスではない。

まとめ

VuePress 1.x の Markdown は、素の Markdown に Component 埋め込み・名前付き Container・frontmatter を足した拡張版で、当時は小〜中規模のドキュメント / ブログ用途に十分な表現力を持っていた。

2026 年現在、その役割は MDX + Astro / Next.js + content collections に置き換わっている。VuePress 時代の発想（記事メタを frontmatter で持つ、補足ブロックを記法で書く、再利用はコンポーネント化する）はそのまま新しいスタックでも通用するので、当時の設計記録としてこの記事を残しておく。