Creation:2025-02-07Last update:2026-05-19

    Markdown / 서식 있는 텍스트 콘텐츠

    Intlayer는 Markdown 구문을 사용하여 정의된 서식 있는 텍스트 콘텐츠를 지원합니다. 이를 통해 블로그, 기사 등과 같이 서식이 풍부한 콘텐츠를 쉽게 작성하고 유지 관리할 수 있습니다.

    Markdown 콘텐츠 선언

    md 함수를 사용하거나 (Markdown 구문이 포함된 경우) 단순한 문자열로 Markdown 콘텐츠를 선언할 수 있습니다.

    버전 8.10.0부터 .content.md 파일에서 직접 Markdown 콘텐츠를 선언할 수 있습니다. Intlayer가 Markdown 콘텐츠를 자동으로 감지하고 구문 분석합니다.

    markdown-file.en.content.md
    ---key: my-markdown-contentdescription: 내 콘텐츠locale: en---# 내 콘텐츠여기에 마크다운 콘텐츠 예시가 있습니다.

    locale 프런트매터 필드는 콘텐츠의 로캘을 정의하는 필드입니다. 선택 사항입니다. 제공되지 않으면 Intlayer는 기본 로캘을 사용하며, 특정 로캘에 대한 번역이 없을 때 대체 로캘로도 사용됩니다.

    파일 구조 예시:

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

    사전 정의에 정의된 속성을 프런트매터에 추가할 수 있습니다.

    Markdown 렌더링

    Intlayer는 Markdown을 렌더링하는 두 가지 독립적인 방법을 제공합니다:

    1. useIntlayer를 통한 방식 — Intlayer는 프레임워크의 네이티브 출력(JSX, VNode, HTML 문자열)으로 md 노드를 자동으로 변환합니다.

      • 프런트매터는 분석되어 .metadata로 노출됩니다. 렌더링은 두 가지 수준에서 재정의할 수 있습니다. MarkdownProvider(또는 프레임워크 동등 기능)를 통한 전역 설정과 .use()를 통한 노드별 로컬 설정입니다. 두 가지를 결합할 수 있으며, .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 파서를 사용하여 마크다운을 렌더링합니다.

    .use() 메서드를 사용하여 특정 노드에 대한 로컬 재정의를 제공할 수도 있습니다:

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

    문자열로 Markdown을 가져올 수 있습니다:

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

    그리고 다음과 같이 마크다운 메타데이터에 접근할 수 있습니다:

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

    2. 도우미 유틸리티 (Markdown 문자열 전용)

    이러한 유틸리티는 순수 Markdown 문자열만 렌더링하며 useIntlayer와 독립적입니다. 사전 외의 출처에서 Markdown을 렌더링해야 할 때 사용하세요.

    <MarkdownRenderer /> 컴포넌트

    특정 옵션으로 Markdown 문자열을 렌더링합니다.

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

    useMarkdownRenderer() 훅

    사전 구성된 렌더러 함수를 가져옵니다.

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

    renderMarkdown() 유틸리티

    컴포넌트 외부 렌더링용 독립 실행형 유틸리티.

    tsx
    import { renderMarkdown } from "react-intlayer/markdown";const jsx = renderMarkdown("# 내 제목", { 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 맵에서 확인됩니다.

    자체 마크다운 렌더러를 사용할 수도 있습니다:

    AppProvider.tsx
    import { MarkdownProvider } from "react-intlayer/markdown";export const AppProvider = ({ children }) => (  <MarkdownProvider    renderMarkdown={async (md) => {      // Use dynamic import to reduce the bundle size of your application      const { renderMarkdown } = await import('react-intlayer/markdown');      return renderMarkdown(md);    }}  >    {children}  </MarkdownProvider>);
    Markdown 렌더러를 동적으로 가져오는 것은 애플리케이션 번들 크기를 줄이는 좋은 방법입니다.

    서스펜스 (Suspense)

    Intlayer Markdown 렌더러는 동적으로 로드됩니다. 최적화되어 있지만 기본 구문 분석기 청크는 약 55kb입니다. 이를 동기적으로 로드하면 초기 페이지 렌더링이 지연되고 FCP(First Contentful Paint)가 저하됩니다.

    UI 차단을 방지하기 위해 Intlayer는 React의 Suspense API와 통합됩니다. 백그라운드에서 구문 분석기를 가져오고 다운로드하는 동안 Promise를 던집니다.

    Intlayer Markdown을 렌더링하는 구성 요소를 <Suspense> 경계로 래핑하십시오. 이렇게 하면 청크가 다운로드되는 동안 현지화된 대체 상태가 표시되어 나머지 DOM이 즉시 렌더링될 수 있습니다.

    경고: <Suspense> 경계를 제공하지 않으면 React는 55kb 청크가 완전히 로드될 때까지 루트 수준에서 일시 중지하거나 전체 구성 요소 트리의 렌더링을 차단합니다.

    Next.js 앱 라우터에서는 클라이언트 구성 요소에 대해 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;

    서버 사이드 렌더링 (SSR) 및 하이드레이션

    remark / rehype와 같은 다른 마크다운 파서와 비교할 때, Intlayer 마크다운은 의존성이 없으며 클라이언트와 서버 사이드 모두에서 실행됩니다.

    그러나 Intlayer는 서버 사이드 렌더링(SSR) 프레임워크(Next.js App Router, React Router, Nuxt, SvelteKit 등)를 위해 파싱을 최적화했습니다.

    원시 마크다운 문자열을 클라이언트에 전송하고 브라우저에서 파싱하는 방식(성능 저하를 유발함) 대신, Intlayer는 서버에서 마크다운을 추상 구문 트리(AST)로 사전 파싱할 수 있도록 지원합니다.

    서버 사이드에서 해당 프레임워크의 Intlayer 패키지에 있는 parseMarkdown 함수를 사용하여 직렬화 가능한 AST(ParsedMarkdown 객체)를 생성하고, 이를 프론트엔드로 직접 전달할 수 있습니다. 모든 Intlayer 렌더링 유틸리티(<MarkdownRenderer>, useMarkdownRenderer 등)는 이 AST 객체를 자동으로 수용하여 원활하게 렌더링합니다.

    서버/클라이언트 아키텍처 예시

    server.ts
    import { parseMarkdown } from "react-intlayer/markdown";// 1. 서버에서: 마크다운을 직렬화 가능한 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} />;}

    이 패턴을 통해 마크다운 파싱 로직을 서버에서 완벽히 실행함으로써 클라이언트 사이드 실행 시간을 크게 단축하고 초기 하이드레이션 속도를 개선할 수 있습니다.

    옵션 참조

    이러한 옵션은 MarkdownProvider, MarkdownRenderer, useMarkdownRenderer 및 renderMarkdown에 전달될 수 있습니다.

    Option Type Default 설명
    forceBlock boolean false 출력을 블록 수준 요소(예: <div>)로 래핑하도록 강제합니다.
    forceInline boolean false 출력을 인라인 요소(예: <span>)로 래핑하도록 강제합니다.
    tagfilter boolean true 위험한 HTML 태그를 제거하여 보안을 강화하기 위해 GitHub 태그 필터를 활성화합니다.
    preserveFrontmatter boolean false true인 경우 Markdown 문자열의 시작 부분에 있는 프런트매터가 제거되지 않습니다.
    components Overrides {} HTML 태그를 사용자 정의 구성 요소에 매핑(예: { h1: MyHeading }).
    wrapper Component null 렌더링된 Markdown을 래핑하는 사용자 정의 구성 요소입니다.
    renderMarkdown Function null 기본 Markdown 컴파일러를 완전히 교체하는 사용자 정의 렌더링 기능입니다.
    중첩
    HTML