著者:
    作成:2025-02-07最終更新:2026-05-19

    Markdown / Rich Text Content

    Intlayerは、Markdown構文を使用して定義されたリッチテキストコンテンツをサポートしています。これにより、ブログ、記事など、リッチなフォーマットを持つコンテンツを簡単に記述および維持できます。

    Markdownコンテンツの宣言

    md関数を使用するか、単純に文字列として（Markdownシンタックスを含む場合）Markdownコンテンツを宣言できます。

    バージョン8.10.0以降、.content.mdファイルでMarkdownコンテンツを直接宣言できます。Intlayerは Markdownコンテンツを自動的に検出して解析します。

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: My contentlocale: en---# My contentHere an example of markdown content

    localeフロントマターフィールドはコンテンツのロケールを定義するフィールドです。これはオプションです。提供されない場合、Intlayerはデフォルトロケールを使用します。これは特定のロケールに対して翻訳が利用できない場合のフォールバックロケールとしても使用されます。

    ファイル構造の例：

    text
    content├── markdown-file.en.content.md├── markdown-file.fr.content.md└── markdown-file.es.content.md

    Dictionary definitionで定義されているプロパティをフロントマターに追加できます

    Markdown のレンダリング

    Intlayer は Markdown をレンダリングするための 2 つの独立した方法を提供します:

    1. useIntlayer 経由 — Intlayer は自動的に md ノードをフレームワークのネイティブ出力 (JSX、VNode、HTML 文字列) に変換します。

      • Frontmatter は解析され、.metadata として公開されます。レンダリングはグローバルに MarkdownProvider (またはフレームワークと同等のもの) で、ノードごとにローカルで .use() で、2 つのレベルでオーバーライドできます。両者は組み合わせることができます。.use() は MarkdownProvider に優先し、MarkdownProvider はデフォルトに優先します。

    2. ヘルパーユーティリティ — <MarkdownRenderer />、useMarkdownRenderer()、および renderMarkdown() は、生の Markdown 文字列のみ を受け入れるスタンドアロンツールです。これらは useIntlayer から独立しており、それが返す装飾されたノードでは機能しません。

    Markdown レンダリングは MDX をサポートしています — Markdown 内で JSX/フレームワークコンポーネントを名前で直接使用できます。

    1. 自動レンダリング（useIntlayer経由）

    Markdownノードは直接JSXとしてレンダリングできます。

    App.tsx
    import { useIntlayer } from "react-intlayer";import { MarkdownProvider } from "react-intlayer/markdown";const AppContent = () => {  const { myMarkdownContent } = useIntlayer("app");  return <div>{myMarkdownContent}</div>;};const App = () => (  <MarkdownProvider    components={{      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,      MyButton: (props) => <button {...props} />, // MDXコンポーネント    }}  >    <AppContent />  </MarkdownProvider>);
    MarkdownProviderが存在しない場合、intlayerはデフォルトのMarkdown to JSXパーサーを使用してMarkdownをレンダリングします。

    .use()メソッドを使用して特定のノードのローカルオーバーライドを提供することもできます：

    tsx
    {myMarkdownContent.use({  h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,})}

    Markdownを文字列として取得できます：

    tsx
    {myMarkdownContent.value}{String(myMarkdownContent)}{myMarkdownContent.toString()}

    また、Markdownのメタデータにアクセスできます：

    tsx
    {myMarkdownContent.metadata}{myMarkdownContent.metadata.title}

    2. ヘルパーユーティリティ（Markdown文字列のみ）

    これらのユーティリティはraw Markdown文字列をレンダリングし、useIntlayerに依存しません。辞書以外のソースからMarkdownをレンダリングする必要がある場合に使用してください。

    <MarkdownRenderer /> コンポーネント

    特定のオプションで Markdown 文字列をレンダリングします。

    tsx
    import { MarkdownRenderer } from "react-intlayer/markdown";<MarkdownRenderer forceBlock={true} tagfilter={true}>  {"# My Title"}</MarkdownRenderer>

    useMarkdownRenderer() Hook

    事前に設定されたレンダラー関数を取得します。

    tsx
    import { useMarkdownRenderer } from "react-intlayer/markdown";const renderMarkdown = useMarkdownRenderer({  forceBlock: true,  components: { h1: (props) => <h1 {...props} className="custom" /> }});return renderMarkdown("# My Title");

    renderMarkdown() ユーティリティ

    コンポーネント外でレンダリングするためのスタンドアロンユーティリティ。

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# My Title", { forceBlock: true });

    MarkdownProvider を使用したグローバル設定

    MarkdownProvider（またはそのフレームワーク相当）は、アプリケーション全体の Markdown レンダリングパイプラインを設定します。自動的な useIntlayer レンダリングとヘルパーユーティリティの両方に適用されます。ここで設定されたオプションはデフォルトです — .use() はノードレベルでそれらをオーバーライドします。

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    components={{      h1: (props) => <h1 style={{color: 'green'}} {...props} />,      a: ({ href, ...props }) => <a style={{color: 'red'}} {...props} />,      MyCustomJSXComponent: (props) => <span style={{color: 'red'}} {...props} />,    }}  >    {children}  </MarkdownProvider>);
    MDX がサポートされています — Markdown 内で使用されるコンポーネント名（例：<MyCustomJSXComponent />）は components マップに対して解決されます。

    独自の Markdown レンダラーを使用することもできます：

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    renderMarkdown={async (md) => {      // アプリケーションのバンドルサイズを削減するために動的インポートを使用してください      const { renderMarkdown } = await import('react-intlayer/markdown');      return renderMarkdown(md);    }}  >    {children}  </MarkdownProvider>);
    Markdown レンダラーを動的にインポートすることは、アプリケーションのバンドルサイズを削減するためのよい方法です。

    Suspense

    Intlayer Markdown レンダラーは動的に読み込まれます。最適化されていますが、基盤となるパーサーチャンクは約 55kb です。これを同期的に読み込むと、初期ページレンダリングが遅延し、First Contentful Paint (FCP) が低下します。

    UI をブロックするのを防ぐため、Intlayer は React の Suspense API と統合されています。バックグラウンドでパーサーを取得し、ダウンロード中に Promise をスローします。

    Intlayer Markdown をレンダリングするコンポーネントを <Suspense> 境界でラップします。これにより、チャンクがダウンロード中にローカライズされたフォールバック状態が表示され、DOM の残りが即座にレンダリングできます。

    警告: <Suspense> 境界を指定しない場合、React はルートレベルで一時停止するか、55kb チャンク全体が完全に読み込まれるまでコンポーネントツリー全体のレンダリングをブロックします。

    Next.js App Router では、クライアントコンポーネント用に React Suspense を使用するか、サーバーコンポーネント用に loading.tsx ファイルを使用できます。

    クライアントコンポーネント:

    components/MyComponent.tsx
    "use client";import { useIntlayer } from "next-intlayer";import { Suspense } from "react";const MyComponent = () => {const markdownContent = useIntlayer("my-markdown");return (  <Suspense fallback={<div>Loading...</div>}>{markdownContent}</Suspense>);};

    loading.tsx を使用したサーバーコンポーネント:

    app/loading.tsx
    export default function Loading() {return <div>Loading...</div>;}
    app/page.tsx
    import { useIntlayer } from "next-intlayer/server";const MyPage = () => {const markdownContent = useIntlayer("my-markdown");return <div>{markdownContent}</div>;};export default MyPage;

    Server-Side Rendering (SSR) と Hydration

    remark / rehype などの他の Markdown パーサーと比較して、Intlayer Markdown は依存関係がなく、クライアント側とサーバー側の両方で実行されます。

    しかし Intlayer は Server-Side Rendering (SSR) フレームワーク（Next.js App Router、React Router、Nuxt、SvelteKit など）用にパースを最適化しています。

    生の Markdown 文字列をクライアントに送信してブラウザーで解析する代わりに（パフォーマンス低下を招きます）、Intlayer では Markdown をサーバー上の Abstract Syntax Tree (AST) に事前解析することができます。

    フレームワークの Intlayer パッケージから parseMarkdown 関数をサーバー側で使用して、シリアライズ可能な AST（ParsedMarkdown オブジェクト）を生成し、フロントエンドに直接渡すことができます。すべての Intlayer レンダリング ユーティリティ（<MarkdownRenderer>、useMarkdownRenderer など）は、このAST オブジェクトを自動的に受け入れ、シームレスにレンダリングします。

    Server/Client アーキテクチャの例

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. サーバー上で: markdown を シリアライズ可能な AST に解析しますexport const loader = async () => {  const markdownString = "## My title \n\nLorem Ipsum";  const ast = parseMarkdown(markdownString);  // AST を JSON としてクライアントに返します  return Response.json({ content: ast });};
    client.tsx
    import { useLoaderData } from "react-router";import { MarkdownRenderer } from "react-intlayer/markdown";// 2. クライアント上で: AST を再解析せずに直接レンダリングしますexport default function Page() {  const { content } = useLoaderData();  // レンダラーは生の文字列または解析された AST のいずれかを受け入れます  return <MarkdownRenderer content={content} />;}

    このパターンにより、markdown の解析ロジックが完全にサーバー上で実行され、クライアント側の実行時間が大幅に削減され、初期ハイドレーション速度が向上します。

    オプションリファレンス

    これらのオプションは MarkdownProvider、MarkdownRenderer、useMarkdownRenderer、renderMarkdown に渡すことができます。

    Option Type Default Description
    forceBlock boolean false 出力をブロックレベル要素（例：<div>）でラップすることを強制します。
    forceInline boolean false 出力をインライン要素（例：<span>）でラップすることを強制します。
    tagfilter boolean true GitHub Tag Filter を有効にして、危険な HTML タグを削除することで、セキュリティを向上させます。
    preserveFrontmatter boolean false true の場合、Markdown 文字列の先頭にある frontmatter は削除されません。
    components Overrides {} HTML タグをカスタムコンポーネントにマップするオブジェクト（例：{ h1: MyHeading }）。
    wrapper Component null レンダリングされた Markdown をラップするカスタムコンポーネント。
    renderMarkdown Function null デフォルトの Markdown コンパイラを完全に置き換えるカスタムレンダリング関数。
    ネスティング
    HTML