@intlayer/docs 8.11.1 → 8.11.2

package/docs/ru/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "Разрешить предварительный синтаксический анализ AST Markdown для SSR / гидратации"
   - version: 8.10.0
     date: 2026-05-19
     changes: "Добавлена поддержка файлов `.content.md`"
@@ -661,6 +664,164 @@ export class MyComponent {
 
 ---
 
+## Рендеринг на стороне сервера (SSR) и гидратация
+
+По сравнению с другими парсерами Markdown, такими как remark / rehype, Intlayer Markdown не имеет зависимостей и работает как на клиенте, так и на сервере.
+
+Однако Intlayer оптимизирует синтаксический анализ для фреймворков серверного рендеринга (SSR) (таких как Next.js App Router, React Router, Nuxt, SvelteKit и т. д.).
+
+Вместо отправки необработанных строк Markdown клиенту и их анализа в браузере (что приводит к снижению производительности), Intlayer позволяет предварительно проанализировать Markdown в абстрактное синтаксическое дерево (AST) на сервере.
+
+Вы можете использовать функцию `parseMarkdown` из пакета Intlayer вашего фреймворка на стороне сервера для генерации сериализуемого 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. На сервере: преобразовать markdown в сериализуемое 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. Преобразовать markdown в сериализуемое AST на сервере
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. Отрендерить AST напрямую
+      // В серверном компоненте это работает бесшовно и передает 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. Получить и преобразовать markdown в 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. На сервере: преобразовать markdown в сериализуемое 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 обычно разрешает данные на сервере во время первоначальной загрузки и выполняет гидратацию на клиенте. Вы можете использовать резолверы для передачи 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. На сервере: преобразовать markdown в сериализуемое 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>
+
+Этот подход гарантирует, что логика анализа Markdown полностью выполняется на сервере, что значительно сокращает время выполнения на стороне клиента и повышает скорость первоначальной гидратации.
+
 ## Справочник по опциям
 
 Эти параметры могут быть переданы в `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` и `renderMarkdown`.

package/docs/tr/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "SSR / hidrasyon için Markdown AST'sinin önceden ayrıştırılmasına izin ver"
   - version: 8.10.0
     date: 2026-05-19
     changes: "`.content.md` dosyaları için destek eklendi"
@@ -1149,6 +1152,164 @@ export class MyComponent {
 
 ---
 
+## Sunucu Tarafı İşleme (SSR) ve Hidrasyon
+
+Remark / rehype gibi diğer Markdown ayrıştırıcılarıyla karşılaştırıldığında, Intlayer Markdown bağımlılık içermez ve hem istemci hem de sunucu tarafında çalışır.
+
+Ancak Intlayer, Sunucu Tarafı İşleme (SSR) çerçeveleri (Next.js App Router, React Router, Nuxt, SvelteKit vb. gibi) için ayrıştırmayı optimize etmiştir.
+
+Ham Markdown dizelerini istemciye göndermek ve tarayıcıda ayrıştırmak (bu da performans kaybına neden olur) yerine, Intlayer, Markdown'u sunucuda bir Soyut Sözdizimi Ağacı (AST) olarak önceden ayrıştırmanıza olanak tanır.
+
+Serileştirilebilir bir AST (`ParsedMarkdown` nesnesi) oluşturmak için sunucu tarafında çerçevenizin Intlayer paketindeki `parseMarkdown` işlevini kullanabilir ve bunu doğrudan ön uca aktarabilirsiniz. Tüm Intlayer işleme yardımcı programları ( `<MarkdownRenderer>`, `useMarkdownRenderer` vb. gibi) bu AST nesnesini otomatik olarak kabul eder ve sorunsuz bir şekilde işler.
+
+### Sunucu/İstemci Mimarisinde Örnek
+
+<Tabs group="framework">
+  <Tab label="React Router" value="react">
+
+    ```tsx fileName="server.ts"
+    import { parseMarkdown } from "react-intlayer/markdown";
+
+    // 1. Sunucuda: Markdown'u serileştirilebilir bir AST'ye ayrıştırın
+    export const loader = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // AST'yi istemciye JSON olarak döndürün
+      return Response.json({ content: ast });
+    };
+    ```
+
+    ```tsx fileName="client.tsx"
+    import { useLoaderData } from "react-router";
+    import { MarkdownRenderer } from "react-intlayer/markdown";
+
+    // 2. İstemcide: AST'yi yeniden ayrıştırmadan doğrudan işleyin
+    export default function Page() {
+      const { content } = useLoaderData();
+
+      // İşleyici, ham bir dizeyi veya ayrıştırılmış AST'yi kabul eder
+      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. Sunucuda Markdown'u serileştirilebilir bir AST'ye ayrıştırın
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. AST'yi doğrudan işleyin
+      // Bir Server Component içinde bu sorunsuz çalışır ve gerekirse AST'yi
+    // doğrudan alt istemci bileşenlerine iletir.
+      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. Sunucuda markdown'u getirin ve bir AST'ye ayrıştırın
+    const { data: ast } = await useAsyncData('markdown', () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      return parseMarkdown(markdownString);
+    });
+    </script>
+
+    <template>
+      <!-- 2. İstemcide: AST'yi yeniden ayrıştırmadan doğrudan işleyin -->
+      <MarkdownRenderer :content="ast" />
+    </template>
+    ```
+
+  </Tab>
+  <Tab label="SvelteKit" value="svelte">
+
+    ```typescript fileName="+page.server.ts"
+    import { parseMarkdown } from "svelte-intlayer/markdown";
+
+    // 1. Sunucuda: Markdown'u serileştirilebilir bir AST'ye ayrıştırın
+    export const load = async () => {
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // AST'yi istemciye döndürün
+      return { content: ast };
+    };
+    ```
+
+    ```svelte fileName="+page.svelte"
+    <script lang="ts">
+      import { MarkdownRenderer } from "svelte-intlayer/markdown";
+      export let data;
+    </script>
+
+    <!-- 2. İstemcide: AST'yi yeniden ayrıştırmadan doğrudan işleyin -->
+    <MarkdownRenderer value={data.content} />
+    ```
+
+  </Tab>
+  <Tab label="Angular" value="angular">
+
+    Angular SSR, verileri genellikle ilk yükleme sırasında sunucuda çözümler ve istemcide hidrasyon gerçekleştirir. AST'yi iletmek için çözümleyiciler (resolvers) kullanabilirsiniz.
+
+    ```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. Sunucuda: Markdown'u serileştirilebilir bir AST'ye ayrıştırın
+        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. İstemcide: AST'yi yeniden ayrıştırmadan doğrudan işleyin
+        this.route.data.subscribe((data) => {
+          this.renderedMarkdown = this.markdownService.renderMarkdown(
+            data.markdownAst
+          ) as string;
+        });
+      }
+    }
+    ```
+
+  </Tab>
+</Tabs>
+
+Bu model, Markdown ayrıştırma mantığının tamamen sunucuda çalıştırılmasını sağlayarak istemci tarafındaki yürütme süresini önemli ölçüde azaltır ve ilk hidrasyon hızını artırır.
+
 ## Seçenek Referansı
 
 Bu seçenekler `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` ve `renderMarkdown`a iletilebilir.

package/docs/uk/dictionary/markdown.md

@@ -17,6 +17,9 @@ slugs:
   - content
   - markdown
 history:
+  - version: 8.11.0
+    date: 2026-05-28
+    changes: "Дозволити попередній синтаксичний аналіз AST Markdown для SSR / гідратації"
   - version: 8.10.0
     date: 2026-05-19
     changes: "Додано підтримку файлів `.content.md`"
@@ -1149,6 +1152,164 @@ export class MyComponent {
 
 ---
 
+## Рендеринг на стороні сервера (SSR) та гідратація
+
+У порівнянні з іншими парсерами Markdown, такими як remark / rehype, Intlayer Markdown не має залежностей і працює як на клієнті, так і на сервері.
+
+Однак Intlayer оптимізує синтаксичний аналіз для фреймворків серверного рендерингу (SSR) (таких як Next.js App Router, React Router, Nuxt, SvelteKit тощо).
+
+Замість надсилання необроблених рядків Markdown клієнту та їх аналізу в браузері (що призводить до зниження продуктивності), Intlayer дозволяє попередньо проаналізувати Markdown в абстрактне синтаксичне дерево (AST) на сервері.
+
+Ви можете використовувати функцію `parseMarkdown` з пакету Intlayer вашого фреймворку на стороні сервера для генерації серіалізованого 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. На сервері: перетворити markdown на серіалізоване 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. Перетворити markdown на серіалізоване AST на сервері
+      const markdownString = "## My title \n\nLorem Ipsum";
+      const ast = parseMarkdown(markdownString);
+
+      // 2. Відрендерити AST безпосередньо
+      // У серверному компоненті це працює безшовно і передає 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. Отримати та перетворити markdown на 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. На сервері: перетворити markdown на серіалізоване 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 зазвичай отримує дані на сервері під час початкового завантаження та виконує гідратацію на клієнті. Ви можете використовувати резолвери для передачі 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. На сервері: перетворити markdown на серіалізоване 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>
+
+Цей підхід гарантує, що логіка аналізу Markdown повністю виконується на сервері, що значно скорочує час виконання на стороні клієнта та підвищує швидкість початкової гідратації.
+
 ## Довідник опцій
 
 Ці параметри можна передати до `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer` та `renderMarkdown`.