zfb
GitHub リポジトリ

検索したい単語を入力

いつでも検索バーを開ける

Markdown と HTML ページ

.md と .html ファイルを .tsx と並ぶ第一級のページエントリとして使う — 同じルーティング規約、異なるレンダリングパス。

このページの内容

pages/ 内の .md と .html ファイルがどのようにルートになるか。.mdページで認識されるフロントマターキー、v1 のレイアウトの制限、.htmlページの静的アセットコントラクト、そして両者が共有する SSG 専用の制約を 扱います。

zfb は合計 7 つのページソース拡張子を受け付けます — .tsx・.ts・.jsx・ .js（いずれも同じ方法でバンドルされるスクリプトページ）に加えて、この ページで扱う .mdx・.md・.html です。7 つすべてが pages/ の下で同じ ファイルシステムルーティング規約に従います — pages/about.md と pages/about.tsx はどちらもルート /about を生成します。異なるのは各拡張子 が取るレンダリングパスです。.mdx は .md と MDX パイプラインを共有し、 同じフロントマターキーを受け付けます（後述の .md ページのセクションを 参照）。受け付けられる拡張子の全リストは ルーティング を 参照してください。

.md ページ

pages/ に置かれた .md ファイルは、コンテンツコレクションを駆動するのと 同じ MDX パイプラインを通してコンパイルされます。エンジンはコンパイルされた 本文を最小限の HTML シェルで包み、他のページと同様に dist/ へ書き出します。

フロントマターキー

.md ページで読まれるフロントマターキーは 2 つだけです（v1 コントラクト）:

KeyTypeDefaultEffect
titlestringURL slugHTML シェル内の <title> 要素を設定します。
langstring"en"<html lang="…"> を設定します。

他のすべてのキーは 暗黙的に無視されます。スキーマ検証はなく、未知の キーに対するエラーもありません — それらは単にレンダリング出力に現れない だけです。

---
title: About this project
lang: en
---

## What is this?

A short description of the project.

title のスラッグフォールバックはファイルステム — 拡張子を除いた最後の パスセグメント — から導かれます。pages/about.md は "about" に、 pages/docs/intro.md は "intro"（"docs/intro" ではなく）にフォール バックします。より具体的なタイトルが必要なときはフロントマターの title: を使ってください。

相対リンク

相対 Markdown リンクは標準の MDX パイプラインを通り、ソースファイルを基準に 解決されます。

v1 のレイアウトの制限

v1 では .md ページに レイアウトシステムがありません。フロントマターの layout: キーは効果を持ちません。エンジンは常に MDX 本文を包む素の HTML ドキュメントを生成します — <DefaultLayout> も、カスタムラッパーもありません。

共有レイアウト（ナビゲーション、ヘッダー、フッター）が必要なら、代わりに .tsx ページを書いて Markdown コンテンツをコンポーネントとして import するか、 コンテンツコレクションを使ってください。

v1 では .md ページにレイアウトサポートがありません

layout: フロントマターは .md ページエントリでは無視されます。Markdown コンテンツの周りにレイアウトラッパーが必要なら .tsx を使ってください。

SSG 専用

.md ページエントリは SSG 専用 です。SSR モード（Cloudflare Worker ランタイム）ではサポートされません。サーバサイドレンダリングが必要なら .tsx を使ってください。

.html ページ

pages/ 内の .html ファイルは、JavaScript レンダリングや後処理を一切 行わずに dist/ へそのままコピーされます。エンジンはそれらを、たまたま ルーティングツリーの下に存在する静的アセットとして扱います。

完全ドキュメント要件

ファイルは 完全な HTML ドキュメント でなければなりません。<!doctype （大文字小文字を区別しない）または <html で始まる必要があります。素の HTML フラグメント（包む構造のない <div> や <p> ブロック）は v1 の対象外で、 未定義の出力を生みます。

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Static page</title>
  </head>
  <body>
    <h1>Hello from a static .html page</h1>
  </body>
</html>

後処理なし

.html ページは JS レンダリングパイプラインを完全にバイパスするため、 以下は 適用されません:

  • ベースパス書き換え — サイトが base プレフィックス（例: /pj/site/）を使っていても、ファイル内の絶対的な href/src 値は書き 換えられません。

  • リンク正規化 — .tsx と .md ページが通るリンク正規化処理は 実行されません。

  • Sitemap への登録 — .html ページのルートは生成される sitemap.xml に自動的に追加されません。

これらのいずれかが必要なら、代わりに .md か .tsx を使ってください。

SSG 専用

.html ページエントリは SSG 専用 です。SSR モードではサポートされません。

共通: SSG 専用の制約

.md、.mdx、.html ページはビルド時（SSG）のページソースです。動的ルートの skip gate が適用されるのは .md と .html だけです。ブラケット付きの .md / .html ファイル名は paths() を export できないため、警告付きでスキップされます。 ブラケット付きの .mdx ページはスキャナに受け入れられ、paths() 向けの MDX モジュール export surface を使えます。静的（パラメータ化されていない）な .md、 .mdx、.html ページパスは正しく動作します。

適切な拡張子の選び方

SituationRecommended extension
レイアウトを伴うリッチな JSX ページ.tsx
共有レイアウト不要の、コンテンツのみのシンプルなページ.md
処理を必要としない、事前作成済みの静的 HTML ファイル.html
sitemap に寄与する、またはベースパスを使うページ.tsx または .md
サーバサイドレンダリングするページ.tsx

関連項目

  • ルーティング — ファイルからルートへの完全なマッピング表。

  • フロントマター — .tsx ページの統一フロントマター コントラクト（TSX のリテラルのみのルールと出力拡張子の優先順位を含む）。

  • HTML 以外のページ — .tsx ページから XML、JSON、 プレーンテキストを出力する。

  • Content Collections — content/ 下の .md / .mdx ファイル向けの getCollection() API。

Revision History

作成更新