@intlayer/docs 8.11.1 → 8.11.2

package/docs/ko/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "SSR / 하이드레이션을 위한 Markdown AST 사전 파싱 허용"
   - version: 8.10.0
     date: 2026-05-19
     changes: "`.content.md` 파일 지원 추가"
@@ -1149,6 +1152,164 @@ export class MyComponent {
 
 ---
 
+## 서버 사이드 렌더링 (SSR) 및 하이드레이션
+
+remark / rehype와 같은 다른 마크다운 파서와 비교할 때, Intlayer 마크다운은 의존성이 없으며 클라이언트와 서버 사이드 모두에서 실행됩니다.
+
+그러나 Intlayer는 서버 사이드 렌더링(SSR) 프레임워크(Next.js App Router, React Router, Nuxt, SvelteKit 등)를 위해 파싱을 최적화했습니다.
+
+원시 마크다운 문자열을 클라이언트에 전송하고 브라우저에서 파싱하는 방식(성능 저하를 유발함) 대신, Intlayer는 서버에서 마크다운을 추상 구문 트리(AST)로 사전 파싱할 수 있도록 지원합니다.
+
+서버 사이드에서 해당 프레임워크의 Intlayer 패키지에 있는 `parseMarkdown` 함수를 사용하여 직렬화 가능한 AST(`ParsedMarkdown` 객체)를 생성하고, 이를 프론트엔드로 직접 전달할 수 있습니다. 모든 Intlayer 렌더링 유틸리티(`<MarkdownRenderer>`, `useMarkdownRenderer` 등)는 이 AST 객체를 자동으로 수용하여 원활하게 렌더링합니다.
+
+### 서버/클라이언트 아키텍처 예시
+
+<Tabs group="framework">
+  <Tab label="React Router" value="react">
+
+    ```tsx fileName="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 });
+    };
+    ```
+
+    ```tsx fileName="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} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="app/page.tsx"
+    import { parseMarkdown } from "next-intlayer/markdown";
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    export default async function Page() {
+      // 1. 서버에서 마크다운을 직렬화 가능한 AST로 파싱
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. AST를 직접 렌더링
+      // 서버 컴포넌트(Server Component) 내에서 원활하게 작동하며, 필요한 경우
+    // 하위 클라이언트 컴포넌트로 AST를 직접 전달합니다.
+      return <MarkdownRenderer content={ast} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue / Nuxt" value="vue">
+
+    ```vue fileName="pages/index.vue"
+    <script setup lang="ts">
+    import { parseMarkdown } from "vue-intlayer/markdown";
+    import { MarkdownRenderer } from "vue-intlayer/markdown";
+
+    // 1. 서버에서 마크다운을 가져오고 AST로 파싱
+    const { data: ast } = await useAsyncData('markdown', () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      return parseMarkdown(markdownString);
+    });
+    </script>
+
+    <template>
+      <!-- 2. 클라이언트에서: 재파싱 없이 AST를 직접 렌더링 -->
+      <MarkdownRenderer :content="ast" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="SvelteKit" value="svelte">
+
+    ```typescript fileName="+page.server.ts"
+    import { parseMarkdown } from "svelte-intlayer/markdown";
+
+    // 1. 서버에서: 마크다운을 직렬화 가능한 AST로 파싱
+    export const load = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // AST를 클라이언트에 반환
+      return { content: ast };
+    };
+    ```
+
+    ```svelte fileName="+page.svelte"
+    <script lang="ts">
+      import { MarkdownRenderer } from "svelte-intlayer/markdown";
+      export let data;
+    </script>
+
+    <!-- 2. 클라이언트에서: 재파싱 없이 AST를 직접 렌더링 -->
+    <MarkdownRenderer value={data.content} />
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    Angular SSR은 일반적으로 초기 로드 시 서버에서 데이터를 확인하고 클라이언트에서 하이드레이션을 수행합니다. 확인자(resolvers)를 사용하여 AST를 전달할 수 있습니다.
+
+    ```typescript fileName="app.resolver.ts"
+    import { Injectable } from "@angular/core";
+    import { Resolve } from "@angular/router";
+    import { parseMarkdown, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Injectable({ providedIn: "root" })
+    export class MarkdownResolver implements Resolve<ParsedMarkdown> {
+      resolve(): ParsedMarkdown {
+        const markdownString = "## My title \n\nLorem Ipsum";
+        // 1. 서버에서: 마크다운을 직렬화 가능한 AST로 파싱
+        return parseMarkdown(markdownString);
+      }
+    }
+    ```
+
+    ```typescript fileName="app.component.ts"
+    import { Component } from "@angular/core";
+    import { ActivatedRoute } from "@angular/router";
+    import { IntlayerMarkdownService, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Component({
+      selector: "app-root",
+      template: `<div [innerHTML]="renderedMarkdown"></div>`,
+    })
+    export class AppComponent {
+      renderedMarkdown: string = "";
+
+      constructor(
+        private route: ActivatedRoute,
+        private markdownService: IntlayerMarkdownService
+      ) {
+        // 2. 클라이언트에서: 재파싱 없이 AST를 직접 렌더링
+        this.route.data.subscribe((data) => {
+          this.renderedMarkdown = this.markdownService.renderMarkdown(
+            data.markdownAst
+          ) as string;
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+이 패턴을 통해 마크다운 파싱 로직을 서버에서 완벽히 실행함으로써 클라이언트 사이드 실행 시간을 크게 단축하고 초기 하이드레이션 속도를 개선할 수 있습니다.
+
 ## 옵션 참조
 
 이러한 옵션은 `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` 및 `renderMarkdown`에 전달될 수 있습니다.

package/docs/pl/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "Zezwalaj na wstępne parsowanie AST Markdown dla SSR / hydratacji"
   - version: 8.10.0
     date: 2026-05-19
     changes: "Dodano obsługę plików `.content.md`"
@@ -1149,6 +1152,164 @@ export class MyComponent {
 
 ---
 
+## Renderowanie po stronie serwera (SSR) i hydratacja
+
+W porównaniu do innych parserów Markdown, takich jak remark / rehype, Intlayer Markdown jest pozbawiony zależności i działa zarówno po stronie klienta, jak i serwera.
+
+Jednak Intlayer optymalizuje parsowanie dla frameworków renderowania po stronie serwera (SSR) (takich jak Next.js App Router, React Router, Nuxt, SvelteKit itp.).
+
+Zamiast wysyłać surowe ciągi Markdown do klienta i parsować je w przeglądarce (co powoduje spadek wydajności), Intlayer pozwala na wstępne sparsowanie Markdown do abstrakcyjnego drzewa składniowego (AST) na serwerze.
+
+Możesz użyć funkcji `parseMarkdown` z pakietu Intlayer swojego frameworka po stronie serwera, aby wygenerować serializowalne AST (obiekt `ParsedMarkdown`) i przekazać je bezpośrednio do frontendu. Wszystkie narzędzia renderujące Intlayer (takie jak `<MarkdownRenderer>`, `useMarkdownRenderer` itp.) automatycznie akceptują ten obiekt AST i renderują go bez zakłóceń.
+
+### Przykład w architekturze serwer/klient
+
+<Tabs group="framework">
+  <Tab label="React Router" value="react">
+
+    ```tsx fileName="server.ts"
+    import { parseMarkdown } from "react-intlayer/markdown";
+
+    // 1. Na serwerze: Sparsuj markdown do serializowalnego AST
+    export const loader = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // Zwróć AST jako JSON do klienta
+      return Response.json({ content: ast });
+    };
+    ```
+
+    ```tsx fileName="client.tsx"
+    import { useLoaderData } from "react-router";
+    import { MarkdownRenderer } from "react-intlayer/markdown";
+
+    // 2. Na kliencie: Renderuj AST bezpośrednio bez ponownego parsowania
+    export default function Page() {
+      const { content } = useLoaderData();
+
+      // Renderer akceptuje surowy ciąg znaków lub sparsowane AST
+      return <MarkdownRenderer content={content} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="app/page.tsx"
+    import { parseMarkdown } from "next-intlayer/markdown";
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    export default async function Page() {
+      // 1. Sparsuj markdown do serializowalnego AST na serwerze
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. Renderuj AST bezpośrednio
+      // W Server Component działa to bezproblemowo i przekazuje AST
+    // bezpośrednio do bazowych komponentów klienckich, jeśli to konieczne.
+      return <MarkdownRenderer content={ast} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue / Nuxt" value="vue">
+
+    ```vue fileName="pages/index.vue"
+    <script setup lang="ts">
+    import { parseMarkdown } from "vue-intlayer/markdown";
+    import { MarkdownRenderer } from "vue-intlayer/markdown";
+
+    // 1. Pobierz i sparsuj markdown do AST na serwerze
+    const { data: ast } = await useAsyncData('markdown', () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      return parseMarkdown(markdownString);
+    });
+    </script>
+
+    <template>
+      <!-- 2. Na kliencie: Renderuj AST bezpośrednio bez ponownego parsowania -->
+      <MarkdownRenderer :content="ast" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="SvelteKit" value="svelte">
+
+    ```typescript fileName="+page.server.ts"
+    import { parseMarkdown } from "svelte-intlayer/markdown";
+
+    // 1. Na serwerze: Sparsuj markdown do serializowalnego AST
+    export const load = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // Zwróć AST do klienta
+      return { content: ast };
+    };
+    ```
+
+    ```svelte fileName="+page.svelte"
+    <script lang="ts">
+      import { MarkdownRenderer } from "svelte-intlayer/markdown";
+      export let data;
+    </script>
+
+    <!-- 2. Na kliencie: Renderuj AST bezpośrednio bez ponownego parsowania -->
+    <MarkdownRenderer value={data.content} />
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    Angular SSR zazwyczaj pobiera dane na serwerze podczas początkowego ładowania i hydratuje na kliencie. Możesz użyć resolverów do przekazania AST.
+
+    ```typescript fileName="app.resolver.ts"
+    import { Injectable } from "@angular/core";
+    import { Resolve } from "@angular/router";
+    import { parseMarkdown, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Injectable({ providedIn: "root" })
+    export class MarkdownResolver implements Resolve<ParsedMarkdown> {
+      resolve(): ParsedMarkdown {
+        const markdownString = "## My title \n\nLorem Ipsum";
+        // 1. Na serwerze: Sparsuj markdown do serializowalnego AST
+        return parseMarkdown(markdownString);
+      }
+    }
+    ```
+
+    ```typescript fileName="app.component.ts"
+    import { Component } from "@angular/core";
+    import { ActivatedRoute } from "@angular/router";
+    import { IntlayerMarkdownService, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Component({
+      selector: "app-root",
+      template: `<div [innerHTML]="renderedMarkdown"></div>`,
+    })
+    export class AppComponent {
+      renderedMarkdown: string = "";
+
+      constructor(
+        private route: ActivatedRoute,
+        private markdownService: IntlayerMarkdownService
+      ) {
+        // 2. Na kliencie: Renderuj AST bezpośrednio bez ponownego parsowania
+        this.route.data.subscribe((data) => {
+          this.renderedMarkdown = this.markdownService.renderMarkdown(
+            data.markdownAst
+          ) as string;
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+Ten wzorzec zapewnia, że logika parsowania Markdown jest wykonywana całkowicie na serwerze, co znacznie skraca czas wykonywania po stronie klienta i poprawia szybkość początkowej hydratacji.
+
 ## Opcje referencyjne
 
 Te opcje można przekazać do `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` i `renderMarkdown`.

package/docs/pt/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "Permitir a pré-análise do AST do Markdown para SSR / hidratação"
   - version: 8.10.0
     date: 2026-05-19
     changes: "Adicionado suporte a arquivos `.content.md`"
@@ -1149,6 +1152,164 @@ export class MyComponent {
 
 ---
 
+## Renderização no Lado do Servidor (SSR) e Hidratação
+
+Em comparação com outros analisadores de Markdown, como remark / rehype, o Intlayer Markdown é livre de dependências e roda tanto no cliente quanto no servidor.
+
+No entanto, o Intlayer otimiza a análise para frameworks de Renderização no Lado do Servidor (SSR) (como Next.js App Router, React Router, Nuxt, SvelteKit, etc.).
+
+Em vez de enviar strings Markdown brutas para o cliente e analisá-las no navegador (o que acarreta uma perda de desempenho), o Intlayer permite pré-analisar o Markdown em uma Árvore de Sintaxe Abstrata (AST) no servidor.
+
+Você pode usar a função `parseMarkdown` do pacote Intlayer do seu framework no lado do servidor para gerar uma AST serializável (objeto `ParsedMarkdown`) e passá-la diretamente para o frontend. Todos os utilitários de renderização do Intlayer (como `<MarkdownRenderer>`, `useMarkdownRenderer`, etc.) aceitam automaticamente esse objeto AST e o renderizam perfeitamente.
+
+### Exemplo em uma Arquitetura Servidor/Cliente
+
+<Tabs group="framework">
+  <Tab label="React Router" value="react">
+
+    ```tsx fileName="server.ts"
+    import { parseMarkdown } from "react-intlayer/markdown";
+
+    // 1. No servidor: Analisar o markdown em uma AST serializável
+    export const loader = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // Retornar a AST como JSON para o cliente
+      return Response.json({ content: ast });
+    };
+    ```
+
+    ```tsx fileName="client.tsx"
+    import { useLoaderData } from "react-router";
+    import { MarkdownRenderer } from "react-intlayer/markdown";
+
+    // 2. No cliente: Renderizar a AST diretamente sem reanalisar
+    export default function Page() {
+      const { content } = useLoaderData();
+
+      // O renderizador aceita uma string bruta ou a AST analisada
+      return <MarkdownRenderer content={content} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Next.js" value="nextjs">
+
+    ```tsx fileName="app/page.tsx"
+    import { parseMarkdown } from "next-intlayer/markdown";
+    import { MarkdownRenderer } from "next-intlayer/markdown";
+
+    export default async function Page() {
+      // 1. Analisar o markdown em uma AST serializável no servidor
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. Renderizar a AST diretamente
+      // Em um Server Component, isso funciona perfeitamente e passa a AST
+    // diretamente para os componentes de cliente subjacentes, se necessário.
+      return <MarkdownRenderer content={ast} />;
+    }
+    ```
+
+  </Tab>
+  <Tab label="Vue / Nuxt" value="vue">
+
+    ```vue fileName="pages/index.vue"
+    <script setup lang="ts">
+    import { parseMarkdown } from "vue-intlayer/markdown";
+    import { MarkdownRenderer } from "vue-intlayer/markdown";
+
+    // 1. Buscar e analisar o markdown em uma AST no servidor
+    const { data: ast } = await useAsyncData('markdown', () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      return parseMarkdown(markdownString);
+    });
+    </script>
+
+    <template>
+      <!-- 2. No cliente: Renderizar a AST diretamente sem reanalisar -->
+      <MarkdownRenderer :content="ast" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="SvelteKit" value="svelte">
+
+    ```typescript fileName="+page.server.ts"
+    import { parseMarkdown } from "svelte-intlayer/markdown";
+
+    // 1. No servidor: Analisar o markdown em uma AST serializável
+    export const load = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // Retornar a AST para o cliente
+      return { content: ast };
+    };
+    ```
+
+    ```svelte fileName="+page.svelte"
+    <script lang="ts">
+      import { MarkdownRenderer } from "svelte-intlayer/markdown";
+      export let data;
+    </script>
+
+    <!-- 2. No cliente: Renderizar a AST diretamente sem reanalisar -->
+    <MarkdownRenderer value={data.content} />
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    O SSR do Angular normalmente resolve os dados no servidor durante o carregamento inicial e hidrata no cliente. Você pode usar resolvers para passar a AST.
+
+    ```typescript fileName="app.resolver.ts"
+    import { Injectable } from "@angular/core";
+    import { Resolve } from "@angular/router";
+    import { parseMarkdown, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Injectable({ providedIn: "root" })
+    export class MarkdownResolver implements Resolve<ParsedMarkdown> {
+      resolve(): ParsedMarkdown {
+        const markdownString = "## My title \n\nLorem Ipsum";
+        // 1. No servidor: Analisar o markdown em uma AST serializável
+        return parseMarkdown(markdownString);
+      }
+    }
+    ```
+
+    ```typescript fileName="app.component.ts"
+    import { Component } from "@angular/core";
+    import { ActivatedRoute } from "@angular/router";
+    import { IntlayerMarkdownService, type ParsedMarkdown } from "angular-intlayer/markdown";
+
+    @Component({
+      selector: "app-root",
+      template: `<div [innerHTML]="renderedMarkdown"></div>`,
+    })
+    export class AppComponent {
+      renderedMarkdown: string = "";
+
+      constructor(
+        private route: ActivatedRoute,
+        private markdownService: IntlayerMarkdownService
+      ) {
+        // 2. No cliente: Renderizar a AST diretamente sem reanalisar
+        this.route.data.subscribe((data) => {
+          this.renderedMarkdown = this.markdownService.renderMarkdown(
+            data.markdownAst
+          ) as string;
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+Esse padrão garante que a lógica de análise do Markdown seja executada inteiramente no servidor, reduzindo significativamente o tempo de execução no cliente e melhorando a velocidade de hidratação inicial.
+
 ## Referência de opções
 
 Essas opções podem ser passadas para `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` e `renderMarkdown`.