@asyncapi/generator 2.6.0 → 2.7.1

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

@@ -18,13 +18,13 @@ Here is a list of `ag` options and their equivalents in the AsyncAPI CLI:
 - **-i, --install**
   - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --install`
 
-- **-n, --no-overwrite <glob>**
+- **-n, --no-overwrite &#x3C;glob&#x3E;**
   - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --no-overwrite <glob>`
 
-- **-o, --output <outputDir>**
+- **-o, --output &#x3C;outputDir&#x3E;**
   - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --output <outputDir>`
 
-- **-p, --param <name=value>**
+- **-p, --param &#x3C;name&#x3D;value&#x3E;**
   - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --param <name=value>`
 
 - **--force-write**
@@ -33,7 +33,7 @@ Here is a list of `ag` options and their equivalents in the AsyncAPI CLI:
 - **--watch-template**
   - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --watch`
 
-- **--map-base-url <url:folder>**
+- **--map-base-url &#x3C;url:folder&#x3E;**
   - **AsyncAPI CLI equivalent:** `asyncapi generate fromTemplate <ASYNCAPI> <TEMPLATE> --map-base-url <url:folder>`
 
 ## Migration Steps
@@ -67,4 +67,4 @@ Run the updated commands to ensure they work as expected and verify that the out
 **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).
+**Support**: For any issues with CLI, create an issue in [CLI repository](https://github.com/asyncapi/cli).

package/docs/migration-nunjucks-react.md

@@ -112,7 +112,7 @@ export default function({ asyncapi }) {
 
 ### 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.
+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
 

package/docs/nunjucks-render-engine.md

@@ -75,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](/apps/nunjucks-filters) that are by default included in the generator library.
+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.
+
+> **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.
 
 ```

package/lib/conditionalGeneration.js

@@ -0,0 +1,162 @@
+const log = require('loglevel');
+const logMessage = require('./logMessages');
+const jmespath = require('jmespath');
+
+/**
+ * Determines whether the generation of a file or folder should be skipped
+ * based on conditions defined in the template configuration.
+ *
+ * @param {Object} templateConfig - The template configuration containing conditional logic.
+ * @param {string} matchedConditionPath - The matched path used to find applicable conditions.
+ * @param {Object} templateParams - Parameters passed to the template.
+ * @param {AsyncAPIDocument} asyncapiDocument - The AsyncAPI document used for evaluating conditions.
+ * @returns {Promise<boolean>} A promise that resolves to `true` if the condition is met, allowing the file or folder to render; otherwise, resolves to `false`. 
+ */
+async function isGenerationConditionMet (
+  templateConfig,
+  matchedConditionPath,
+  templateParams,
+  asyncapiDocument 
+) {
+  const conditionFilesGeneration = templateConfig?.conditionalFiles?.[matchedConditionPath] || {};
+  const conditionalGeneration = templateConfig?.conditionalGeneration?.[matchedConditionPath] || {};
+
+  const config = Object.keys(conditionFilesGeneration).length > 0 
+    ? conditionFilesGeneration 
+    : conditionalGeneration;
+
+  const subject = config?.subject;
+
+  // conditionalFiles becomes deprecated with this PR, and soon will be removed.
+  // TODO: https://github.com/asyncapi/generator/issues/1553
+  if (Object.keys(conditionFilesGeneration).length > 0 && subject) {
+    return conditionalFilesGenerationDeprecatedVersion(
+      asyncapiDocument,
+      templateConfig,
+      matchedConditionPath,
+      templateParams
+    );
+  } else if (Object.keys(conditionalGeneration).length > 0) {
+    // Case when the subject is present in conditionalGeneration
+    if (subject) {
+      return conditionalSubjectGeneration(
+        asyncapiDocument,
+        templateConfig,
+        matchedConditionPath
+      );
+    }
+    return conditionalParameterGeneration(templateConfig,matchedConditionPath,templateParams);
+  }
+};
+
+/**
+ * Evaluates whether a template path should be conditionally generated 
+ * based on a parameter defined in the template configuration.
+ * @private
+ * @async
+ * @function conditionalParameterGeneration
+ * @param {Object} templateConfig - The full template configuration object.
+ * @param {string} matchedConditionPath - The path of the file/folder being conditionally generated.
+ * @param {Object} templateParams - The parameters passed to the generator, usually user input or default values.
+ * @returns {Promise<boolean>} - Resolves to `true` if the parameter passes validation, `false` otherwise.
+ */
+async function conditionalParameterGeneration(templateConfig, matchedConditionPath, templateParams) {
+  const conditionalGenerationConfig = templateConfig.conditionalGeneration?.[matchedConditionPath];
+  const parameterName = conditionalGenerationConfig.parameter;
+  const parameterValue = templateParams[parameterName];
+  return validateStatus(parameterValue, matchedConditionPath, templateConfig);
+}
+
+/**
+ * Determines whether a file should be conditionally included based on the provided subject expression
+ * and optional validation logic defined in the template configuration.
+ * @private
+ * @param {Object} asyncapiDocument - The parsed AsyncAPI document instance used for context evaluation.
+ * @param {Object} templateConfig - The configuration object that contains `conditionalFiles` rules.
+ * @param {string} matchedConditionPath - The path of the file/folder being conditionally generated.
+ * @param {Object} templateParams - The parameters passed to the generator, usually user input or default values.
+ * @returns {Boolean} - Returns `true` if the file should be included; `false` if it should be skipped.
+ */
+async function conditionalFilesGenerationDeprecatedVersion (
+  asyncapiDocument,
+  templateConfig,
+  matchedConditionPath,
+  templateParams
+) {
+  return conditionalSubjectGeneration(asyncapiDocument, templateConfig, matchedConditionPath, templateParams);
+};
+
+/**
+ * Determines whether a file should be conditionally included based on the provided subject expression
+ * and optional validation logic defined in the template configuration.
+ * @private
+ * @param {Object} asyncapiDocument - The parsed AsyncAPI document instance used for context evaluation.
+ * @param {Object} templateConfig - The configuration object that contains `conditionalFiles` rules.
+ * @param {String} matchedConditionPath - The relative path to the directory of the source file.
+ * @param {Object} templateParams - Parameters passed to the template.
+ * @returns {Boolean} - Returns `true` if the file should be included; `false` if it should be skipped.
+ */
+async function conditionalSubjectGeneration (
+  asyncapiDocument,
+  templateConfig,
+  matchedConditionPath,
+  templateParams
+
+) {
+  const fileCondition = templateConfig.conditionalGeneration?.[matchedConditionPath] || templateConfig.conditionalFiles?.[matchedConditionPath];
+  if (!fileCondition || !fileCondition.subject) {
+    return true; 
+  }
+  const { subject } = fileCondition;
+  const server = templateParams.server && asyncapiDocument.servers().get(templateParams.server);
+  const source = jmespath.search({
+    ...asyncapiDocument.json(),
+    ...{
+      server: server ? server.json() : undefined,
+    },
+  }, subject);
+
+  if (!source) {
+    log.debug(logMessage.relativeSourceFileNotGenerated(matchedConditionPath, subject));
+    return false;
+  } 
+  return validateStatus(source, matchedConditionPath, templateConfig);
+}
+
+/**
+ * Validates the argument value based on the provided validation schema.
+ *
+ * @param {any} argument The value to validate.
+ * @param {String} matchedConditionPath The matched condition path.
+ * @param {Object} templateConfig - The template configuration containing conditional logic.
+ * @return {Promise<Boolean>} A promise that resolves to false if the generation should be skipped, true otherwise.
+ */
+async function validateStatus(
+  argument,
+  matchedConditionPath,
+  templateConfig
+) {
+  const validation = templateConfig.conditionalGeneration?.[matchedConditionPath]?.validate || templateConfig.conditionalFiles?.[matchedConditionPath]?.validate;
+  if (!validation) {
+    return false; 
+  }
+ 
+  const isValid = validation(argument);
+
+  if (!isValid) {
+    if (templateConfig.conditionalGeneration?.[matchedConditionPath]) {
+      log.debug(logMessage.conditionalGenerationMatched(matchedConditionPath));
+    } else {
+      // conditionalFiles becomes deprecated with this PR, and soon will be removed.
+      // TODO: https://github.com/asyncapi/generator/issues/1553
+      log.debug(logMessage.conditionalFilesMatched(matchedConditionPath));
+    }
+ 
+    return false;
+  }
+  return true;
+}
+
+module.exports = {
+  isGenerationConditionMet
+};

package/lib/filtersRegistry.js

@@ -16,7 +16,7 @@ module.exports.registerFilters = async (nunjucks, templateConfig, templateDir, f
   await registerLocalFilters(nunjucks, templateDir, filtersDir);
   registerConfigFilters(nunjucks, templateDir, templateConfig);
 
-  // Register Nunjucks filters from the 'nunjucks-filters' module without needing to list them explicitly in package.json
+  // Register Nunjucks filters from the 'nunjucks-filters' module without needing to list them in package.json or .ageneratorrc file.
   addFilters(nunjucks, nunjucksFilters);
 };