@intlayer/docs 8.10.0-canary.0 → 8.10.0

package/docs/en-GB/dictionary/markdown.md

@@ -19,64 +19,63 @@ slugs:
 history:
   - version: 8.10.0
     date: 2026-05-19
-    changes: "Add `.content.md` files support"
+    changes: "Added support for `.content.md` files"
   - version: 8.5.0
     date: 2026-03-24
-    changes: "Add `intlayerMarkdown` plugin object; use `app.use(intlayerMarkdown)` instead of `app.use(installIntlayerMarkdown)`"
+    changes: "Added `intlayerMarkdown` plugin object; use `app.use(intlayerMarkdown)` instead of `app.use(installIntlayerMarkdown)`"
   - version: 8.5.0
     date: 2026-03-24
-    changes: "move import from `{{framework}}-intlayer` to `{{framework}}-intlayer/markdown`"
+    changes: "Moved import from `{{framework}}-intlayer` to `{{framework}}-intlayer/markdown`"
   - version: 8.0.0
     date: 2026-01-22
-    changes: "Add MarkdownRenderer / useMarkdownRenderer / renderMarkdown utility and forceInline option"
+    changes: "Added MarkdownRenderer / useMarkdownRenderer / renderMarkdown utility and forceInline option"
   - version: 8.0.0
     date: 2026-01-18
     changes: "Automatic decoration of markdown content, MDX and SSR support"
   - version: 5.5.10
     date: 2025-06-29
-    changes: "Init history"
+    changes: "Initialised history"
 ---
 
 # Markdown / Rich Text Content
 
-Intlayer supports rich text content defined using Markdown syntax. This allows you to easily write and maintain content with rich formatting, such as blogs, articles, and more.
+Intlayer supports rich text content defined using Markdown syntax. This allows you to easily write and maintain richly-formatted content like blogs, articles, and more.
 
-## Part 1: Declaring Markdown Content
+## Declaring Markdown Content
 
 You can declare Markdown content using the `md` function or simply as a string (if it contains Markdown syntax).
 
 <Tabs>
   <Tab label=".content.md" value=".content.md">
-    Since version `8.10.0`, you can declare Markdown content directly in `.content.md` files. Intlayer will
-    automatically detect and parse the Markdown content.
+    Starting from version `8.10.0`, you can declare Markdown content directly in `.content.md` files. Intlayer will automatically detect and parse the Markdown content.
 
-    ```md fileName="markdown-file.en.content.md"
+    ```md fileName="markdown-file.en-GB.content.md"
     ---
     key: my-markdown-content
     description: My content
-    locale: en
+    locale: en-GB
     ---
 
     # My content
 
-    Here an example of markdown content
+    Here is a markdown content example
     ```
 
-    The `locale` frontmatter field is the field that define the locale of the content. It is optional. If not provided, Intlayer will use the default locale, which is also used as fallback locale if no translation is available for a specific locale.
+    The `locale` front-matter field is the field that defines the content locale. It is optional. If not provided, Intlayer will use the default locale, which is also used as a fallback locale if no translation is available for a specific locale.
 
-    Example of file structure:
+    Files structure example:
 
     ```text
     content/
-    ├── en/
-    │   └── markdown-file.en.content.md
+    ├── en-GB/
+    │   └── markdown-file.en-GB.content.md
     ├── fr/
     │   └── markdown-file.fr.content.md
     └── es/
         └── markdown-file.es.content.md
     ```
 
-    You can add in front-matter any properties defined in the [Dictionary definition](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md)
+    You can add in the front-matter any properties defined in the [Dictionary Definition](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en-GB/dictionary/content_file.md)
 
   </Tab>
   <Tab label="Manual Wrapping" value="manual-wrapping">
@@ -96,33 +95,34 @@ You can declare Markdown content using the `md` function or simply as a string (
     ```
 
   </Tab>
-  <Tab label="Automatic Detection" value="automatic-detection">
-    If the string contains common Markdown indicators (like headers, lists, links, etc.), Intlayer will automatically transform it.
+  <Tab label="External Files" value="external-files">
+    Import `.md` files directly using the `file` function.
 
     ```typescript fileName="markdownDictionary.content.ts"
+    import { md, file, t } from "intlayer";
+
     export default {
       key: "app",
-      contentAutoTransformation: true, // Enable automatic detection of Markdown content - Can be set globally in intlayer.config.ts
       content: {
-        myMarkdownContent: "## My title \n\nLorem Ipsum",
+        content: t({
+          en: md(file("./myMarkdown.en-GB.md")),
+          fr: md(file("./myMarkdown.fr.md")),
+        }),
       },
     };
     ```
 
   </Tab>
-  <Tab label="External Files">
-    Import `.md` files directly using the `file` function.
 
-    ```typescript fileName="markdownDictionary.content.ts"
-    import { md, file, t } from "intlayer";
+  <Tab label="Automatic Detection" value="automatic-detection">
+    If the string contains common Markdown indicators (like headings, lists, links, etc.), Intlayer will automatically transform it.
 
+    ```typescript fileName="markdownDictionary.content.ts"
     export default {
       key: "app",
+      contentAutoTransformation: true, // Enable automatic detection of Markdown content - Can be set globally in intlayer.config.ts
       content: {
-        content: t({
-          en: md(file("./myMarkdown.en.md")),
-          fr: md(file("./myMarkdown.fr.md")),
-        }),
+        myMarkdownContent: "## My title \n\nLorem Ipsum",
       },
     };
     ```
@@ -134,11 +134,17 @@ You can declare Markdown content using the `md` function or simply as a string (
 
 ## Rendering Markdown
 
-Rendering can be handled automatically by Intlayer's content system or manually using specialised tools.
+Intlayer provides two independent ways to render Markdown:
+
+1. **Via `useIntlayer`**
+   — Intlayer automatically transforms the `md` node into the framework's native output (JSX, VNode, HTML string).
+   - Frontmatter is parsed and exposed as `.metadata`. You can override the rendering at two levels — globally with `MarkdownProvider` (or framework equivalent) and locally per node with `.use()`. Both can be combined; `.use()` takes precedence over `MarkdownProvider`, which takes precedence over the default.
+
+2. **Helper utilities** — `<MarkdownRenderer />`, `useMarkdownRenderer()`, and `renderMarkdown()` are standalone tools that accept **only raw Markdown strings**. They are independent of `useIntlayer` and do not work with the decorated nodes it returns.
 
-### 1. Automatic Rendering (using `useIntlayer`)
+Markdown rendering supports **MDX** — use any JSX/framework component by name directly inside your Markdown.
 
-When you access content via `useIntlayer`, Markdown nodes are already prepared for rendering.
+### 1. Automatic Rendering (via `useIntlayer`)
 
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
@@ -146,24 +152,54 @@ When you access content via `useIntlayer`, Markdown nodes are already prepared f
 
     ```tsx fileName="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 Component
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
     ```
 
+    > If `MarkdownProvider` is not present, Intlayer will render the markdown using the default Markdown to JSX parser.
+
     You can also provide local overrides for specific nodes using the `.use()` method:
 
     ```tsx
     {myMarkdownContent.use({
-      h1: ({ children }) => <h1 className="text-3xl font-bold">{children}</h1>,
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
     })}
     ```
 
+    You can retrieve the Markdown as a string:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    And you can access your markdown metadata like this:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
+    ```
+
   </Tab>
-  <Tab label="Vue">
-    In Vue, Markdown content can be rendered using the `component` built-in or directly as a node.
+  <Tab label="Vue" value="vue">
+    In Vue, Markdown content can be rendered using the built-in `component` tag or directly as a node.
 
     ```vue fileName="App.vue"
     <script setup>
@@ -176,43 +212,183 @@ When you access content via `useIntlayer`, Markdown nodes are already prepared f
     </template>
     ```
 
+    Configure globally via the `intlayerMarkdown` plugin (supports MDX custom components):
+
+    ```ts fileName="main.ts"
+    import { intlayerMarkdown } from "vue-intlayer/markdown";
+
+    app.use(intlayerMarkdown, {
+      components: {
+        h1: (props) => h('h1', { style: { color: 'green' } }, props.children),
+        MyButton: (props) => h('button', props), // MDX Component
+      },
+    });
+    ```
+
+    > If the `intlayerMarkdown` plugin is not installed, Intlayer will render using the default compiler.
+
+    You can also provide local overrides for specific nodes using the `.use()` method:
+
+    ```vue
+    <component :is="myMarkdownContent.use({
+      h1: (props) => h('h1', { style: { color: 'red' } }, props.children),
+    })" />
+    ```
+
+    You can retrieve the Markdown as a string:
+
+    ```vue
+    {{ myMarkdownContent.value }}
+    {{ String(myMarkdownContent) }}
+    {{ myMarkdownContent.toString() }}
+    ```
+
+    And you can access your markdown metadata like this:
+
+    ```vue
+    <component :is="myMarkdownContent.metadata" />
+    <component :is="myMarkdownContent.metadata.title" />
+    ```
+
   </Tab>
   <Tab label="Svelte" value="svelte">
     Svelte renders Markdown as an HTML string by default. Use `{@html}` to render it.
 
-    ```svelte
+    ```svelte fileName="App.svelte"
     <script lang="ts">
     import { useIntlayer } from "svelte-intlayer";
+    import { MarkdownProvider } from "svelte-intlayer/markdown";
+    import MyHeading from "./MyHeading.svelte";
+
     const content = useIntlayer("app");
     </script>
 
-    {@html $content.myMarkdownContent}
+    <MarkdownProvider components={{ h1: MyHeading }}>
+      {@html $content.myMarkdownContent}
+    </MarkdownProvider>
+    ```
+
+    > If `MarkdownProvider` is not present, Intlayer will render the markdown using the default compiler.
+
+    You can also provide local overrides for specific nodes using the `.use()` method:
+
+    ```svelte
+    {@html $content.myMarkdownContent.use({ ... })}
+    ```
+
+    You can retrieve the Markdown as a string:
+
+    ```svelte
+    {$content.myMarkdownContent.value}
+    {String($content.myMarkdownContent)}
+    {$content.myMarkdownContent.toString()}
+    ```
+
+    And you can access your markdown metadata like this:
+
+    ```svelte
+    {$content.myMarkdownContent.metadata}
+    {$content.myMarkdownContent.metadata.title}
     ```
 
   </Tab>
   <Tab label="Preact" value="preact">
-    Preact supports Markdown nodes directly in the JSX.
+    Preact supports Markdown nodes directly in JSX.
 
     ```tsx fileName="App.tsx"
     import { useIntlayer } from "preact-intlayer";
+    import { MarkdownProvider } from "preact-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 Component
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > If `MarkdownProvider` is not present, Intlayer will render the markdown using the default Markdown to JSX parser.
+
+    You can also provide local overrides for specific nodes using the `.use()` method:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: ({ children }) => <h1 style={{ color: "red" }}>{children}</h1>,
+    })}
+    ```
+
+    You can retrieve the Markdown as a string:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    And you can access your markdown metadata like this:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
     ```
 
   </Tab>
   <Tab label="Solid" value="solid">
-    Solid supports Markdown nodes directly in the JSX.
+    Solid supports Markdown nodes directly in JSX.
 
     ```tsx fileName="App.tsx"
     import { useIntlayer } from "solid-intlayer";
+    import { MarkdownProvider } from "solid-intlayer/markdown";
 
     const AppContent = () => {
       const { myMarkdownContent } = useIntlayer("app");
       return <div>{myMarkdownContent}</div>;
     };
+
+    const App = () => (
+      <MarkdownProvider
+        components={{
+          h1: (props) => <h1 style={{ color: "red" }}>{props.children}</h1>,
+          MyButton: (props) => <button {...props} />, // MDX Component
+        }}
+      >
+        <AppContent />
+      </MarkdownProvider>
+    );
+    ```
+
+    > If `MarkdownProvider` is not present, Intlayer will render the markdown using the default Markdown to JSX parser.
+
+    You can also provide local overrides for specific nodes using the `.use()` method:
+
+    ```tsx
+    {myMarkdownContent.use({
+      h1: (props) => <h1 style={{ color: "red" }}>{props.children}</h1>,
+    })}
+    ```
+
+    You can retrieve the Markdown as a string:
+
+    ```tsx
+    {myMarkdownContent.value}
+    {String(myMarkdownContent)}
+    {myMarkdownContent.toString()}
+    ```
+
+    And you can access your markdown metadata like this:
+
+    ```tsx
+    {myMarkdownContent.metadata}
+    {myMarkdownContent.metadata.title}
     ```
 
   </Tab>
@@ -232,6 +408,8 @@ When you access content via `useIntlayer`, Markdown nodes are already prepared f
     }
     ```
 
+    > If the IntlayerMarkdown provider is not configured, Intlayer will render using the default compiler.
+
     You can also provide local overrides for specific nodes using the `.use()` method:
 
     ```typescript
@@ -240,19 +418,34 @@ When you access content via `useIntlayer`, Markdown nodes are already prepared f
     })
     ```
 
+    You can retrieve the Markdown as a string:
+
+    ```typescript
+    content().myMarkdownContent.value
+    String(content().myMarkdownContent)
+    content().myMarkdownContent.toString()
+    ```
+
+    And you can access your markdown metadata like this:
+
+    ```typescript
+    content().myMarkdownContent.metadata
+    content().myMarkdownContent.metadata.title
+    ```
+
   </Tab>
 </Tabs>
 
-### 2. Manual Rendering & Advanced Tools
+### 2. Helper Utilities (Markdown Strings Only)
 
-If you need to render raw Markdown strings or have more control over the rendering process, use the following tools.
+These utilities render **only raw Markdown strings** and are independent of `useIntlayer`. Use them when you need to render Markdown from sources other than your dictionaries.
 
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
   
     #### `<MarkdownRenderer />` Component
 
-    Render a Markdown string with specific options.
+    Renders a Markdown string with specific options.
 
     ```tsx
     import { MarkdownRenderer } from "react-intlayer/markdown";
@@ -287,7 +480,7 @@ If you need to render raw Markdown strings or have more control over the renderi
     ```
 
   </Tab>
-  <Tab label="Vue">
+  <Tab label="Vue" value="vue">
 
     #### `<MarkdownRenderer />` Component
 
@@ -398,10 +591,10 @@ If you need to render raw Markdown strings or have more control over the renderi
   </Tab>
   <Tab label="Angular" value="angular">
     #### `IntlayerMarkdownService` Service
-    Render a Markdown string using the service.
+    Renders a Markdown string using the service.
 
     ```typescript
-    import { IntlayerMarkdownService } from "angular-intlayer";
+    import { IntlayerMarkdownService } from "angular-intlayer/markdown";
 
     export class MyComponent {
       constructor(private markdownService: IntlayerMarkdownService) {}
@@ -419,7 +612,7 @@ If you need to render raw Markdown strings or have more control over the renderi
 
 ## Global Configuration with `MarkdownProvider`
 
-You can configure Markdown rendering globally for your entire application. This avoids passing the same props to every renderer.
+The `MarkdownProvider` (or its framework equivalent) configures the Markdown rendering pipeline for your entire application. This applies to both the automatic `useIntlayer` rendering and the helper utilities. Options set here are the defaults — `.use()` overrides them at the node level.
 
 <Tabs group="framework">
   <Tab label="React / Next.js" value="react">
@@ -430,8 +623,9 @@ You can configure Markdown rendering globally for your entire application. This
     export const AppProvider = ({ children }) => (
       <MarkdownProvider
         components={{
-          h1: ({ children }) => <h1 className="text-2xl font-bold">{children}</h1>,
-          a: ({ href, children }) => <Link to={href}>{children}</Link>,
+          h1: (props) => <h1 style={{color: 'green'}} {...props} />,
+          a: ({ href, ...props }) => <a style={{color: 'red'}} {...props} />,
+          MyCustomJSXComponent: (props) => <span style={{color: 'red'}} {...props} />,
         }}
       >
         {children}
@@ -439,8 +633,30 @@ You can configure Markdown rendering globally for your entire application. This
     );
     ```
 
+    > MDX is supported — any component name used inside your Markdown (e.g. `<MyCustomJSXComponent />`) is resolved against the `components` map.
+
+    You can also use your own markdown renderer:
+
+    ```tsx fileName="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>
+    );
+    ```
+
+    > Importing your Markdown renderer dynamically is a great way to reduce the bundle size of your application.
+
   </Tab>
-  <Tab label="Vue">
+  <Tab label="Vue" value="vue">
 
     ```typescript fileName="main.ts"
     import { createApp } from "vue";
@@ -464,6 +680,29 @@ You can configure Markdown rendering globally for your entire application. This
     app.mount("#app");
     ```
 
+    You can also use your own markdown renderer:
+
+    ```typescript fileName="main.ts"
+    import { createApp } from "vue";
+    import { intlayer } from "vue-intlayer";
+    import { intlayerMarkdown } from "vue-intlayer/markdown";
+    import App from "./App.vue";
+
+    const app = createApp(App);
+
+    app.use(intlayer);
+    app.use(intlayerMarkdown, {
+      renderMarkdown: async (md) => {
+        const { renderMarkdown } = await import('vue-intlayer/markdown');
+        return renderMarkdown(md);
+      },
+    });
+
+    app.mount("#app");
+    ```
+
+    > Importing your Markdown renderer dynamically is a great way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Svelte" value="svelte">
 
@@ -482,6 +721,25 @@ You can configure Markdown rendering globally for your entire application. This
     </MarkdownProvider>
     ```
 
+    You can also use your own markdown renderer:
+
+    ```svelte fileName="App.svelte"
+    <script lang="ts">
+      import { MarkdownProvider } from "svelte-intlayer/markdown";
+    </script>
+
+    <MarkdownProvider
+      renderMarkdown={async (md) => {
+        const { renderMarkdown } = await import('svelte-intlayer/markdown');
+        return renderMarkdown(md);
+      }}
+    >
+      <slot />
+    </MarkdownProvider>
+    ```
+
+    > Importing your Markdown renderer dynamically is a great way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Preact" value="preact">
 
@@ -499,6 +757,25 @@ You can configure Markdown rendering globally for your entire application. This
     );
     ```
 
+    You can also use your own markdown renderer:
+
+    ```tsx fileName="AppProvider.tsx"
+    import { MarkdownProvider } from "preact-intlayer/markdown";
+
+    export const AppProvider = ({ children }) => (
+      <MarkdownProvider
+        renderMarkdown={async (md) => {
+          const { renderMarkdown } = await import('preact-intlayer/markdown');
+          return renderMarkdown(md);
+        }}
+      >
+        {children}
+      </MarkdownProvider>
+    );
+    ```
+
+    > Importing your Markdown renderer dynamically is a great way to reduce the bundle size of your application.
+
   </Tab>
   <Tab label="Solid" value="solid">
 
@@ -516,38 +793,46 @@ You can configure Markdown rendering globally for your entire application. This
     );
     ```
 
-  </Tab>
-  <Tab label="Angular" value="angular">
+    You can also use your own markdown renderer:
 
-    ```typescript fileName="app.config.ts"
-    import { createIntlayerMarkdownProvider } from "angular-intlayer/markdown";
+    ```tsx fileName="AppProvider.tsx"
+    import { MarkdownProvider } from "solid-intlayer/markdown";
 
-    export const appConfig: ApplicationConfig = {
-      providers: [
-        createIntlayerMarkdownProvider({
-          components: {
-            h1: { class: "text-2xl font-bold" },
-          },
-        }),
-      ],
-    };
+    export const AppProvider = (props) => (
+      <MarkdownProvider
+        renderMarkdown={async (md) => {
+          const { renderMarkdown } = await import('solid-intlayer/markdown');
+          return renderMarkdown(md);
+        }}
+      >
+        {props.children}
+      </MarkdownProvider>
+    );
     ```
 
-  </Tab>
-</Tabs>
+    > Importing your Markdown renderer dynamically is a great way to reduce the bundle size of your application.
 
----
+  </Tab>
+  <Tab label="Angular" value="angular">
 
-## Options Reference
+    ```typescript fileName="app.module.ts"
+    import { NgModule } from '@angular/core';
+    import { IntlayerMarkdownModule } from 'angular-intlayer/markdown';
+
+    @NgModule({
+      imports: [
+        IntlayerMarkdownModule.forRoot({
+          renderMarkdown: async (md) => {
+            const { renderMarkdown } = await import('angular-intlayer/markdown');
+            return renderMarkdown(md);
+          }
+        })
+      ]
+    })
+    export class AppModule {}
+    ```
 
-These options can be passed to `MarkdownProvider`, `MarkdownRenderer`, `useMarkdownRenderer`, and `renderMarkdown`.
+    > Importing your Markdown renderer dynamically is a great way to reduce the bundle size of your application.
 
-| Option                | Type        | Default | Description                                                                           |
-| :-------------------- | :---------- | :------ | :------------------------------------------------------------------------------------ |
-| `forceBlock`          | `boolean`   | `false` | Forces the output to be wrapped in a block-level element (e.g., `<div>`).             |
-| `forceInline`         | `boolean`   | `false` | Forces the output to be wrapped in an inline element (e.g., `<span>`).                |
-| `tagfilter`           | `boolean`   | `true`  | Enables the GitHub Tag Filter for improved security by stripping dangerous HTML tags. |
-| `preserveFrontmatter` | `boolean`   | `false` | If `true`, frontmatter at the beginning of the Markdown string will not be stripped.  |
-| `components`          | `Overrides` | `{}`    | A map of HTML tags to custom components (e.g., `{ h1: MyHeading }`).                  |
-| `wrapper`             | `Component` | `null`  | A custom component to wrap the rendered Markdown.                                     |
-| `renderMarkdown`      | `Function`  | `null`  | A custom rendering function to completely replace the default Markdown compiler.      |
+  </Tab>
+</Tabs>