docs(generator): update latest generator documentation (#3602)

Co-authored-by: asyncapi-bot <[email protected]>
Co-authored-by: Lukasz Gornicki <[email protected]>

markdown/docs/tools/generator/file-templates.md

@@ -7,6 +7,8 @@ weight: 140
 
 > **Note**: This section applies only to the Nunjucks render engine. For information on using the React render engine, refer to the [Generating files with the React render engine](#generating-files-with-the-react-render-engine) section below.
 
+> **Note**: Nunjucks renderer engine is deprecated and will be removed in the future. Use the React renderer engine instead. For more details read notes from release [@asyncapi/generator@2.6.0](https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0).
+
 It is possible to generate files for each specific object in your AsyncAPI documentation using the Nunjucks render engine. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables are available:
 
    - `$$channel$$`, within the template-file you have access to two variables [`channel`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channel) and [`channelName`](https://github.com/asyncapi/parser-api/blob/master/docs/api.md#channels). Where the `channel` contains the current channel being rendered.

markdown/docs/tools/generator/migration-cli.md

@@ -0,0 +1,70 @@
+---
+title: "Migrating from `ag` CLI to AsyncAPI CLI"
+weight: 260
+---
+
+This guide provides detailed instructions on how to transition from the old `ag` Generator CLI  to the new AsyncAPI CLI.
+
+## Options Overview
+
+Here is a list of `ag` options and their equivalents in the AsyncAPI CLI:
+
+- **-d, --disable-hook [hooks...]**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --disable-hook <hookType>=<hookName>`
+
+- **--debug**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --debug`
+
+- **-i, --install**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --install`
+
+- **-n, --no-overwrite &#x3C;glob&#x3E;**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --no-overwrite <glob>`
+
+- **-o, --output &#x3C;outputDir&#x3E;**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --output <outputDir>`
+
+- **-p, --param &#x3C;name&#x3D;value&#x3E;**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --param <name=value>`
+
+- **--force-write**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --force-write`
+
+- **--watch-template**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --watch`
+
+- **--map-base-url &#x3C;url:folder&#x3E;**
+  - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --map-base-url <url:folder>`
+
+## Migration Steps
+
+### 1. Install AsyncAPI CLI
+
+There are multiple different artifacts that AsyncAPI CLI is provided as. Get familiar with the [official CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation).
+
+### 2. Update Your Commands
+
+Replace the deprecated `ag` commands with the AsyncAPI CLI equivalents. Below are examples of how to update your commands:
+
+**Using `ag`**:
+```
+ag ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+```
+
+**Using AsyncAPI CLI**:
+```
+asyncapi generate fromTemplate ./asyncapi.yaml ./template -o ./output -p param1=value1 --debug --install --disable-hook hookType=hookName
+```
+
+Notice that the change basically related to changing from `ag` to `asyncapi generate fromTemplate`.
+
+### 3. Verify and Test
+
+Run the updated commands to ensure they work as expected and verify that the output files are generated correctly.
+
+## Additional Resources
+
+**CLI Documentation**: [AsyncAPI CLI Documentation](https://www.asyncapi.com/docs/tools/cli)
+**Installation**: [AsyncAPI CLI Installation](https://www.asyncapi.com/docs/tools/cli/installation)
+**Usage**: [AsyncAPI CLI Usage](https://www.asyncapi.com/docs/tools/cli/usage)
+**Support**: For any issues with CLI, create an issue in [CLI repository](https://github.com/asyncapi/cli).

markdown/docs/tools/generator/migration-nunjucks-react.md

@@ -0,0 +1,144 @@
+---
+title: "Migrating from Nunjucks to React render engine"
+weight: 250
+---
+
+The AsyncAPI Generator is moving away from Nunjucks templates in favor of React templates. This guide will help you migrate your existing Nunjucks templates to React. For a comprehensive understanding of why we introduced React as an alternative in 2021 and why we're now removing Nunjucks entirely, please read our article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine). The principles discussed in this article still apply to our current transition.
+
+## Step-by-step migration guide
+
+### 1. Update package.json
+
+Change your template configuration in `package.json`:
+
+```json
+{
+"generator": {
+"renderer": "react"
+}
+}
+```
+
+Once the deprecation period has ended, and we remove the default Nunjucks, the React render engine will be used by default and this setting will no longer be needed to configure
+
+### 2. Install dependencies
+
+Install the necessary React dependencies:
+
+```bash
+npm install @asyncapi/generator-react-sdk
+```
+
+### 3. File naming
+
+In Nunjucks, the template's filename directly corresponds to the output file. For example, a template named **index.html** will generate an **index.html** file.
+
+In React, the filename of the generated file is not controlled by the file itself, but rather by the `File` component. The React component itself can be named anything with a `.js` extension because the output filename is controlled by the `name` attribute of the `File` component used inside the template file. Below you can see some examples of filenames: 
+
+Nunjucks: `index.html`
+React: `index.js` or `index.html.js` or `anything-you-want.js`
+
+### 4. Basic template structure
+
+Nunjucks:
+```js
+<h1>{{ asyncapi.info().title() }}</h1>
+<p>{{ asyncapi.info().description() }}</p>
+```
+
+React:
+```js
+import { File } from '@asyncapi/generator-react-sdk';
+
+export default function({ asyncapi }) {
+  return (
+    <File name="index.html">
+      <h1>{asyncapi.info().title()}</h1>
+      <p>{asyncapi.info().description()}</p>
+    </File>
+  );
+}
+```
+
+### 5. Macros and Partials
+
+Replace macros with React components:
+
+Nunjucks:
+```js
+{% macro renderChannel(channel) %}
+  <div class="channel">
+    <h3>{{ channel.address() }}</h3>
+    <p>{{ channel.description() }}</p>
+  </div>
+{% endmacro %}
+
+{{ renderChannel(someChannel) }}
+```
+
+React:
+```js
+// components/Channel.js
+import { Text } from '@asyncapi/generator-react-sdk';
+
+export function Channel({ channel }) {
+  return (
+    <Text>
+      <div className="channel">
+        <h3>{channel.address()}</h3>
+        <p>{channel.description()}</p>
+      </div>
+    </Text>
+  );
+}
+
+// Main template
+import { File, Text } from '@asyncapi/generator-react-sdk';
+import { Channel } from './components/Channel';
+
+export default function({ asyncapi }) {
+  return (
+    <File name="channels.html">
+      <Text>
+        <h2>Channels</h2>
+      </Text>
+      {asyncapi.channels().map(channel => (
+        <Channel channel={channel} />
+      ))}
+    </File>
+  );
+}
+```
+
+### 6. File template 
+
+Check the [detailed guide on file templates](file-templates.md) to learn what is the difference between templating multiple file outputs in Nunjucks and React.
+
+### 7. Models generation
+
+If you have a template written with Nunjucks, it is almost certain that you have your own custom models, classes, or types templates in place. Instead of migrating them to React render engine we strongly advise you to delegate models generation to AsyncAPI Modelina project. Learn more about [how to add models generation using Modelina](https://www.asyncapi.com/docs/tools/generator/model-generation).
+
+## Additional Resources and Information
+
+### Template Examples
+For a complete example of React features in use, please refer to the [AsyncAPI Template for Generator Templates](https://github.com/asyncapi/template-for-generator-templates). The `master` branch demonstrates all React features, while the `nunjucks` branch shows the old Nunjucks implementation. This comparison can be particularly helpful in understanding the differences and migration process.
+
+### Filters to Helpers
+If you've been using Nunjucks filters placed in the `filters` directory, you can still use this functionality in React. However, they should be treated as normal functions that you import into your components. We recommend renaming the `filters` directory to `helpers` to better reflect their new usage in React.
+
+### Hooks Remain Unchanged
+It's important to note that hooks remain unchanged in this migration process. Hooks are not related to the render engine functionality, so you can continue to use them as you have been.
+
+### Testing your migration
+
+After migrating, test your template thoroughly:
+
+1. Run the generator using your new React template
+2. Compare the output with the previous Nunjucks template output
+3. Check for any missing or incorrectly rendered content
+
+Consider implementing snapshot tests for your template before starting the migration. This will ease the review of changes in comparing the content rendered after render engine changes. Snapshot tests allow you to have tests that will persist expected output from Nunjucks template, and compare it with output generated after the migration. Check out an [example of such snapshot integration test for our internal react template we use for development and testing](https://github.com/asyncapi/generator/blob/master/apps/generator/test/integration.test.js#L66).
+
+## Conclusion
+
+Migrating from Nunjucks to React templates may require some initial effort, but it will result in more maintainable code. You can learn more about why we introduced the React render engine from article [React as a Generator Engine](https://www.asyncapi.com/blog/react-as-generator-engine).

markdown/docs/tools/generator/nunjucks-render-engine.md

@@ -3,6 +3,8 @@ title: "Nunjucks render engine"
 weight: 120
 ---
 
+> **Note**: Nunjucks renderer engine is deprecated and will be removed in the future. Use the React renderer engine instead. For more details read notes from release [@asyncapi/generator@2.6.0](https://github.com/asyncapi/generator/releases/tag/%40asyncapi%2Fgenerator%402.6.0).
+
 [Nunjucks](https://mozilla.github.io/nunjucks) is the default render engine, however, we strongly recommend adopting the [React](#react) engine.
 
 ### Common assumptions