@asyncapi/generator 2.5.0 → 2.7.0

package/docs/generator-template.md

@@ -1,5 +1,5 @@
 ---
-title: "Creating a template"
+title: "Creating a template - Python"
 weight: 170
 ---
 
@@ -14,6 +14,29 @@ In this tutorial:
 - You'll create a React template that will use the MQTT broker to allow you to monitor your bedroom's temperature and notify you when the temperature drops or rises above 22 °C.
 - Lastly, create a reusable component for the output code's `sendTemperatureDrop` and `sendTemperatureRise` functions.
 
+## Prerequisites
+
+Before you begin, make sure you have the following set up:
+
+- **Basic Programming Knowledge** – Familiarity with JavaScript and Python.
+- **NPM & PIP** – Required for installing dependencies. Install NPM from the [official guide](https://nodejs.org/en/download) and PIP from the [official guide](https://pip.pypa.io/en/stable/installation).
+- **AsyncAPI CLI** – Used for code generation, install using [CLI installation guide](https://www.asyncapi.com/docs/tools/cli/installation).
+- **Docker** - Required for running MQTT CLI. Install it from the official [Docker](https://docs.docker.com/) website.
+- **Code Editor (VS Code recommended)** – A good code editor is essential for development and debugging.
+- **Knowledge of Template Development** – Review the [Template Development Guide](template-development) to understand the structure and minimum requirements for templates.
+
+> **Note:** In this tutorial, we are using `test.mosquitto.org` as the public broker. However, sometimes it may not be reachable. If you experience any difficulty connecting to it, you can run a broker on your localhost instead.  
+>  
+> If you choose to run the broker on localhost, then in the further steps, replace all occurrences of `test.mosquitto.org` with `localhost` and run the following Docker command:  
+>  
+> ```sh
+> docker run -d --name mosquitto -p 1883:1883 eclipse-mosquitto
+> ```
+>  
+> This starts an Eclipse Mosquitto broker locally on your machine, listening on port 1883.  
+>  
+> If you don’t want to use Docker, you can install Mosquitto manually. Follow the [official installation guide](https://mosquitto.org/download/) for your operating system.
+
 ## Background context
 
 There is a list of [community maintained templates](https://www.asyncapi.com/docs/tools/generator/template#generator-templates-list), but what if you do not find what you need? In that case, you'll create a user-defined template that generates custom output from the generator.
@@ -30,7 +53,7 @@ info:
 
 servers:
   dev:
-    url: test.mosquitto.org
+    url: test.mosquitto.org #in case you're using local mosquitto instance, change this value to localhost.
     protocol: mqtt
 
 channels:
@@ -56,13 +79,6 @@ components:
           type: string
 ```
 
-<Remember>
-
-- To generate code, use the [AsyncAPI CLI](https://www.asyncapi.com/tools/cli). If you don't have the CLI installed, follow [CLI installation guide](/docs/tools/generator/installation-guide#asyncapi-cli).
-- If you are new to AsyncAPI Generator, check out the following docs: [template development](/docs/tools/generator/template-development), which explains the minimum requirements for a template and possible features.
-
-</Remember>
-
 ## Overview of steps
 
 1. Create a new directory for your template named **python-mqtt-client-template**.
@@ -122,7 +138,7 @@ Here's what is contained in the code snippet above:
   - **supportedProtocols** - A list that specifies which protocols are supported by your template.
 - **dependencies** - specifies which version of [`@asyncapi/generator-react-sdk`](https://github.com/asyncapi/generator-react-sdk) should be used.
 
-Navigate to the ****python-mqtt-client-template** directory. Run the command `npm install` on your terminal to install the dependencies specified in **package.json**.
+Navigate to the **python-mqtt-client-template** directory. Run the command `npm install` on your terminal to install the dependencies specified in **package.json**.
 
 ### index.js file
 
@@ -258,7 +274,7 @@ while True:
 
 ```
 
-Run the code above in your terminal using the command `python test.py`. You should see output similar to the snippet below logged on your terminal:
+Navigate to the **python-mqtt-client-template/test/project** directory. Run the command `python test.py` on your terminal. You should see output similar to the snippet below logged on your terminal:
 
 ``` cmd
 New temperature detected 64250266 sent to temperature/changed
@@ -298,18 +314,35 @@ class TemperatureServiceClient:
 
 ### 4. Write script to run the test code
 
-In **package.json** you can have the scripts property that you invoke by calling `npm run <your_script>`. Add these scripts to **package.json**:
+In **package.json** you can have the scripts property that you invoke by calling `npm run <your_script>`. After adding these scripts in **package.json**, it will look like the following code snippet:
 
 ``` json
-    "scripts": {
+    {
+      "name": "python-mqtt-client-template",
+      "version": "0.0.1",
+      "description": "A template that generates a Python MQTT client using MQTT.",
+      "scripts": {
         "test:clean": "rimraf test/project/client.py",
         "test:generate": "asyncapi generate fromTemplate test/fixtures/asyncapi.yml ./ --output test/project --force-write",
         "test:start": "python test/project/test.py",
         "test": "npm run test:clean && npm run test:generate && npm run test:start"
+      },
+      "generator": {
+        "renderer": "react",
+        "apiVersion": "v1",
+        "generator": ">=1.10.0 <2.0.0",
+        "supportedProtocols": ["mqtt"]
+      },
+      "dependencies": {
+        "@asyncapi/generator-react-sdk": "^0.2.25"
+      },
+      "devDependencies": {
+        "rimraf": "^5.0.0"
+      }
     }
 ```
 
-The 4 scripts above do the following:
+The 4 scripts added in **package.json** do the following:
 
 1. `test:clean`: This script uses the `rimraf` package to remove the old version of the file **test/project/client.py** every time you run your test.
 2. `test:generate`: This script uses the AsyncAPI CLI to generate a new version of **client.py**.
@@ -456,7 +489,7 @@ class TemperatureServiceClient:
 You'll then need to template to dynamically generate `sendTemperatureDrop` and `sendTemperatureRise` functions in the generated code based off the AsyncAPI document content. The goal is to write template code that returns functions for channels that the Temperature Service application is subscribed to. The template code to generate these functions will look like this:
 
 ```js
-<Text newLines={2}>
+<Text indent={2} newLines={2}>
   <TopicFunction channels={asyncapi.channels().filterByReceive()} />
 </Text>
 ```
@@ -469,16 +502,16 @@ It's recommended to put reusable components outside the template directory in a
  * As input it requires a list of Channel models from the parsed AsyncAPI document
  */
 export function TopicFunction({ channels }) {
-  const topicsDetails = getTopics(channels)
-  let functions = ''
+  const topicsDetails = getTopics(channels);
+  let functions = '';
 
   topicsDetails.forEach((t) => {
     functions += `def send${t.name}(self, id):
         topic = "${t.topic}"
         self.client.publish(topic, id)\n`
-  })
+  });
 
-  return functions
+  return functions;
 }
 
 /*
@@ -489,19 +522,19 @@ export function TopicFunction({ channels }) {
  * As input it requires a list of Channel models from the parsed AsyncAPI document
  */
 function getTopics(channels) {
-  const channelsCanSendTo = channels
-  let topicsDetails = []
+  const channelsCanSendTo = channels;
+  let topicsDetails = [];
 
   channelsCanSendTo.forEach((ch) => {
-    const topic = {}
-    const operationId = ch.operations().filterByReceive()[0].id()
-    topic.name = operationId.charAt(0).toUpperCase() + operationId.slice(1)
-    topic.topic = ch.address()
+    const topic = {};
+    const operationId = ch.operations().filterByReceive()[0].id();
+    topic.name = operationId.charAt(0).toUpperCase() + operationId.slice(1);
+    topic.topic = ch.address();
 
-    topicsDetails.push(topic)
+    topicsDetails.push(topic);
   })
 
-  return topicsDetails
+  return topicsDetails;
 }
 ```
 
@@ -529,7 +562,7 @@ export default function ({ asyncapi, params }) {
             self.client.connect(mqttBroker)`}
       </Text>
 
-      <Text indent={2}>
+      <Text indent={2} newLines={2}>
         <TopicFunction channels={asyncapi.channels().filterByReceive()} />
       </Text>
     </File>
@@ -616,4 +649,4 @@ Great job completing this tutorial! You have learnt how to use an AsyncAPI file
 
 If you want to tinker with a completed template and see what it would look like in production, check out the [Paho-MQTT template](https://github.com/derberg/python-mqtt-client-template/tree/v1.0.0). You can also check out the accompanying [article about creating MQTT client code](https://www.brainfart.dev/blog/asyncapi-codegen-python).
 
-You can also check out the [MQTT beginners guide](https://medium.com/python-point/mqtt-basics-with-python-examples-7c758e605d4) tutorial to learn more about asynchronous messaging using MQTT.
+You can also check out the [MQTT beginners guide](https://medium.com/python-point/mqtt-basics-with-python-examples-7c758e605d4) tutorial to learn more about asynchronous messaging using MQTT.

package/docs/hooks.md

@@ -11,9 +11,9 @@ The following types of hooks are currently supported:
 
 |Hook type|Description| Return type | Arguments 
 |---|---|---|---|
-| `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | void : Nothing is expected to be returned. | [The generator instance](/api)
-| `generate:after` | Called at the very end of the generation. | void : Nothing is expected to be returned. | [The generator instance](/api)
-| `setFileTemplateName ` | Called right before saving a new file generated by [file template](./file-templates.md). | string : a new filename for the generator to use for the file template. | [The generator instance](/api) and object in the form of `{ "originalFilename" : string }`
+| `generate:before` | Called after registration of all filters and before the generator starts processing of the template. | void : Nothing is expected to be returned. | [The generator instance](api)
+| `generate:after` | Called at the very end of the generation. | void : Nothing is expected to be returned. | [The generator instance](api)
+| `setFileTemplateName` | Called right before saving a new file generated by [file template](file-templates). | string : a new filename for the generator to use for the file template. | [The generator instance](api) and object in the form of `{ "originalFilename" : string }`
 
 ## Location
 

package/docs/installation-guide.md

@@ -8,9 +8,9 @@ You can use the generator library to generate whatever you want in your event-dr
 - [Generator library in Node.js apps](#generator-library-in-nodejs-apps)
   
 ## Prerequisites
-Before you install and use the AsyncAPI CLI and the generator library, ensure you meet the prerequisites below, then [install the CLI](#installation).
-1. Node.js v18.12.0 and higher
-2. Npm v8.19.0 and higher
+Before you install and use the AsyncAPI CLI and the generator library, ensure you meet the prerequisites below, then [install the CLI](https://www.asyncapi.com/docs/tools/cli/installation).
+1. Node.js v18.12.0 or higher
+2. Npm v8.19.0 or higher
    
 To verify the versions of Node and Npm you have, run the following command on your terminal:
 ```
@@ -25,55 +25,9 @@ If you don't have either Node or Npm installed, use the [official node.js instal
 If you have the correct versions installed, proceed to the CLI installation guide below. Otherwise, upgrading the Npm or Node version is lower than the recommended versions specified above.
 
 ## AsyncAPI CLI
-The AsyncAPI CLI tool allows you to do many different things with the [AsyncAPI document](asyncapi-document). You can generate message-based API boilerplate code, documentation, or anything else you need as long as you specify it in your [template](template) or the existing template already supports it. To use the generator via the AsyncAPI CLI, you need to install the AsyncAPI CLI tool.
+The AsyncAPI CLI tool allows you to do many different things with the [AsyncAPI document](asyncapi-document). You can generate message-based API boilerplate code, documentation, or anything else you need as long as you specify it in your [template](template) or the existing template already supports it. To use the generator via the AsyncAPI CLI, you need to install the AsyncAPI CLI tool. For the latest installation instructions, visit the official AsyncAPI CLI [installation guide](https://www.asyncapi.com/docs/tools/cli/installation).
 
-### Installation
-
-#### Install AsyncAPI CLI using NPM
-
-The AsyncAPI CLI is a NodeJS project, so the easiest way to install it is by using the following `npm` command:
-```
-npm install -g @asyncapi/cli
-```
-
-To install a specific version of the generator tool, pass the version during installation:
-```
-npm install -g @asyncapi/cli@{version}
-```
-
-#### MacOS 
-You can install in MacOS by using brew: `brew install asyncapi`. 
-
-#### Linux 
-You can install in Linux by using `dpkg`, a package manager for debian:
-1. `curl -OL https://github.com/asyncapi/cli/releases/latest/download/asyncapi.deb`
-2. `sudo dpkg -i asyncapi.deb`
-
-#### Other operating systems
-For further installation instructions for different operating systems, read the [AsyncAPI CLI documentation](https://github.com/asyncapi/cli#installation).
-
-> **Remember:** 
-> Each [community-developed template](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) is dependent on a certain version of the generator for it to work correctly. Before you install the AsyncAPI CLI, check the template's `package.json` for the version of the AsyncAPI CLI your template is compatible with. Read the [versioning docs](versioning) to learn why it's important to use certain generator versions with your templates.
-
-### Update AsyncAPI CLI
-There are several reasons why you might want to update your generator version:
-* You have the generator tool installed but want to use the latest released features. To upgrade to the latest version, use the command below:
-```
-npm install -g @asyncapi/cli
-```
-* If your template isn't compatible with the latest generator version, you can update it to a specific version of the generator. Check the [version you need](https://github.com/asyncapi/cli/releases) and specify the version you want by using the **@** symbol as shown in the command below:
-```
-npm install -g @asyncapi/cli@{version}
-```
-> Sometimes you have to force additional npm installation like this: `npm install -g --force @asyncapi/cli`
-
-### Uninstall AsyncAPI CLI
-To uninstall the generator, use the following command:
-```
-npm uninstall @asyncapi/cli -g
-``` 
-
-> :memo: **Note:**  To use the generator in your CI/CD pipeline to automate whatever you generate for your event-driven architecture apps, install the AsyncAPI CLI in your pipeline. If you are using GitHub Actions, use [Github Actions for Generator](https://github.com/marketplace/actions/generator-for-asyncapi-documents).
+> :memo: **Note:**  To use the generator in your CI/CD pipeline to automate whatever you generate for your event-driven architecture apps, install the AsyncAPI CLI in your pipeline. If you are using GitHub Actions, use [Github Actions for Generator](https://github.com/marketplace/actions/asyncapi-cli-action).
 
 ## Generator library in Node.js apps
 Use the generator library in your Node.js projects by installing it via the following command: `npm install @asyncapi/generator`.

package/docs/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).

package/docs/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) 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).

package/docs/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
@@ -73,7 +75,9 @@ async function asyncCamelCase(str, callback) {
 }
 ```
 
-In case you have more than one template and want to reuse filters, you can put them in a single library. You can configure such a library in the template configuration under `filters` property. To learn how to add such filters to configuration [read more about the configuration file](#configuration-file).
+In case you have more than one template and want to reuse filters, you can put them in a single library. You can configure such a library in the template configuration under `filters` property. To learn how to add such filters to configuration, [read more about the configuration file](configuration-file).
+
 
+You can also use the official AsyncAPI [nunjucks-filters](https://github.com/asyncapi/generator/tree/master/apps/nunjucks-filters) which is included by default in the generator library.
 
-You can also use the official AsyncAPI [nunjucks-filters](/apps/nunjucks-filters) that are by default included in the generator library.
+> **Note:**  The nunjucks-filters is deprecated, and you should migrate to react-renderer 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).

package/docs/template.md

@@ -23,9 +23,9 @@ You can store template projects on a local drive or as a `git` repository during
 ## Template generation process
 
 1. Template is provided as input to the **Generator**.
-2. **asyncapi** is the original AsyncAPI document injected into your template file by default.
+2. **asyncapi** (which is an instance of AsyncAPIDocument) is injected into your template file by default.
 3. **params** are the parameters you pass to the AsyncAPI CLI. Later, you can also pass these **params** further to other components. 
-4. The generator passes both the original **asyncapi**, the original AsyncAPI document, and the **params** to the **Template Context**.
+4. The generator passes both the **asyncapi**, the **originalAsyncAPI**, and the **params** to the **Template Context**.
 5. Concurrently, the generator passes **Template files** to the **Render engine** as well. AsyncAPI uses two render engines — _react_ and _nunjucks_.
 6. Once the Render Engine receives both the Template Files and the Template Context, it injects all the dynamic values into your react or nunjucks engine, based on the Template Files using the Template Context.
 7. The render engine generates whatever output you may have specified in your template. (i.e. code, documentation, diagrams, pdfs, applications, etc.)

package/docs/usage.md

@@ -8,30 +8,10 @@ There are two ways to use the generator:
 - [Generator library](#using-as-a-modulepackage)
 
 ## AsyncAPI CLI
-Generates whatever you want using templates compatible with AsyncAPI Generator.
-```bash
-USAGE
-  $ asyncapi generate fromTemplate [ASYNCAPI] [TEMPLATE] [-h] [-d <value>] [-i] [--debug] [-n <value>] [-o <value>] [--force-write] [-w] [-p <value>] [--map-base-url <value>]
-
-ARGUMENTS
-  ASYNCAPI  - Local path, url or context-name pointing to AsyncAPI file
-  TEMPLATE  - Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
 
-FLAGS
-  -d, --disable-hook=<value>...  Disable a specific hook type or hooks from a given hook type
-  -h, --help                     Show CLI help.
-  -i, --install                  Installs the template and its dependencies (defaults to false)
-  -n, --no-overwrite=<value>...  Glob or path of the file(s) to skip when regenerating
-  -o, --output=<value>           Directory where to put the generated files (defaults to current directory)
-  -p, --param=<value>...         Additional param to pass to templates
-  -w, --watch                    Watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory.
-  --debug                        Enable more specific errors in the console
-  --force-write                  Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir (defaults to false)
-  --map-base-url=<value>         Maps all schema references from base url to local folder
+### `asyncapi generate fromTemplate ASYNCAPI TEMPLATE`
 
-EXAMPLES
-  $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template --param version=1.0.0 singleFile=true --output ./docs --force-write
-```
+Generates whatever you want using templates compatible with AsyncAPI Generator. For complete command usage and options, refer to the official [AsyncAPI CLI documentation](https://www.asyncapi.com/docs/tools/cli/usage#asyncapi-generate-fromtemplate-asyncapi-template).
 
 All templates are installable npm packages. Therefore, the value of `template` can be anything supported by `npm install`. Here's a summary of the possibilities:
 ```
@@ -60,29 +40,29 @@ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
 
 **The shortest possible syntax:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator
 ```
 
 **Generating from a URL:**
 ```bash
-asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template
+asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template@3.0.0 --use-new-generator
 ```
 
 **Specify where to put the result:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o ./docs
 ```
 
 **Passing parameters to templates:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -p title='Hello from param'
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o ./docs -p title='Hello from param'
 ```
 
 In the template you can use it like this: ` {{ params.title }}`
 
 **Disabling the hooks:**
 ```bash
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs -d generate:before generate:after=foo,bar
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator -o ./docs -d generate:before generate:after=foo,bar
 ```
 
 The generator skips all hooks of the `generate:before` type and `foo`, `bar` hooks of the `generate:after` type.
@@ -101,7 +81,7 @@ asyncapi generate fromTemplate asyncapi.yaml https://github.com/asyncapi/html-te
 
 **Map schema references from baseUrl to local folder:**
 ```bash
-asyncapi generate fromTemplate test/docs/apiwithref.json @asyncapi/html-template -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/
+asyncapi generate fromTemplate test/docs/apiwithref.json @asyncapi/html-template@3.0.0 --use-new-generator -o ./build/ --force-write --map-base-url https://schema.example.com/crm/:./test/docs/
 ```
 
 The parameter `--map-base-url` maps external schema references to local folders.
@@ -114,15 +94,17 @@ Install [Docker](https://docs.docker.com/get-docker/) first, then use docker to
 
 ```bash
 docker run --rm -it \
+--user=root \
 -v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
 -v [GENERATED FILES LOCATION]:/app/output \
-asyncapi/cli [COMMAND HERE]
+asyncapi/cli # docker image [COMMAND HERE]
 
 # Example that you can run inside the cli directory after cloning this repository. First, you specify the mount in the location of your AsyncAPI specification file and then you mount it in the directory where the generation result should be saved.
 docker run --rm -it \
+   --user=root \
    -v ${PWD}/test/fixtures/asyncapi_v1.yml:/app/asyncapi.yml \
    -v ${PWD}/output:/app/output \
-   asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write
+   asyncapi/cli generate fromTemplate -o /app/output /app/asyncapi.yml @asyncapi/html-template@3.0.0 --use-new-generator --force-write
 ```
 Note: Use ``` ` ``` instead of `\` for Windows.
 
@@ -133,7 +115,7 @@ Note: Use ``` ` ``` instead of `\` for Windows.
 Use the following npx command on your terminal:
 
 ```bash
-npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template
+npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator
 ```
 
 ## Using as a module/package
@@ -154,4 +136,4 @@ try {
 }
 ```
 
-See the [API documentation](api) for more examples and full API reference information.
+See the [API documentation](api) for more examples and full API reference information.

package/docs/versioning.md

@@ -18,9 +18,11 @@ It is better to lock a specific version of the template and the generator if you
 Generate HTML with the latest AsyncAPI CLI using the html-template.
 ```
 npm install -g @asyncapi/cli
-asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator
 ```
 
+> AsyncAPI CLI has multiple versions of the generator, and to use the latest version, you may need to pass the `--use-new-generator` flag. For more details you can also check [asyncapi generate fromTemplate ASYNCAPI TEMPLATE](https://www.asyncapi.com/docs/tools/cli/usage#asyncapi-generate-fromtemplate-asyncapi-template)
+
 Generate HTML using a particular version of the AsyncAPI CLI using the html-template.
 
 ```