@asyncapi/generator 1.9.12 → 1.9.14

package/README.md

@@ -12,16 +12,8 @@
 - [List of official generator templates](#list-of-official-generator-templates)
 - [Requirements](#requirements)
 - [Using from the command-line interface (CLI)](#using-from-the-command-line-interface-cli)
-  * [Install the CLI](#install-the-cli)
-  * [Update the CLI](#update-the-cli)
+  * [CLI installation](#cli-installation)
   * [CLI usage](#cli-usage)
-  * [Global templates installed with yarn or npm](#global-templates-installed-with-yarn-or-npm)
-  * [CLI usage examples](#cli-usage-examples)
-  * [CLI usage with Docker](#cli-usage-with-docker)
-  * [CLI usage with npx instead of npm](#cli-usage-with-npx-instead-of-npm)
-- [Using as a module/package](#using-as-a-modulepackage)
-  * [Install the module](#install-the-module)
-  * [Example using the module](#example-using-the-module)
 - [Generator version vs Template version](#generator-version-vs-template-version)
 - [How to create a template](#how-to-create-a-template)
 - [Contributing](#contributing)
@@ -67,221 +59,20 @@ You can find above templates and the ones provided by the community in **[this l
 
 Install both packages using [official installer](https://nodejs.org/en/download/). After installation make sure both packages have proper version by running `node -v` and `npm -v`. To upgrade invalid npm version run `npm install npm@latest -g`
 
-> Generator is tested at the moment against Node 14 and NPM 6. Using newer versions is enabled but we do not guarantee they work well. Please provide feedback on the issues.
+> The generator is tested at the moment against Node 14 and NPM 6. Using newer versions is enabled but we don't guarantee they work well. Please provide feedback via issues.
 
 ## Using from the command-line interface (CLI)
 
-### Install the CLI
-
-To use it as CLI, install generator globally:
-
-```bash
-npm install -g @asyncapi/generator
-```
-
-### Update the CLI
-
-You might want to update your local installation of generator for different reasons:
-
-* You want the latest generator to have its latest features. Perform usual installation and in case you had generator installed already, it will upgrade to latest available:
-    ```bash
-    npm install -g @asyncapi/generator
-    ```
-* You want a specific version of the generator because your template might not be compatible with the latest generator. Check [what version you need](https://github.com/asyncapi/generator/releases) and perform installation, specifying the exact version with the `@` character:
-    ```bash
-    npm install -g @asyncapi/generator@0.50.0
-    ```
-
-> Sometimes you have to force additional npm installation like this: `npm install -g --force @asyncapi/generator`
-
-### CLI usage
-
-```bash
-Usage: ag [options] <asyncapi> <template>
-
-- <asyncapi>: Local path or URL pointing to AsyncAPI specification file
-- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
-
-Options:
-  -V, --version                  output the version number
-  -d, --disable-hook [hooks...]  disable a specific hook type or hooks from given hook type
-  --debug                        enable more specific errors in the console
-  -i, --install                  installs the template and its dependencies (defaults to false)
-  -n, --no-overwrite <glob>      glob or path of the file(s) to skip when regenerating
-  -o, --output <outputDir>       directory where to put the generated files (defaults to current directory)
-  -p, --param <name=value>       additional param to pass to templates
-  --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)
-  --watch-template               watches the template directory and the AsyncAPI document, and re-generate the files when changes occur. Ignores the output directory. This flag should be used only for template development.
-  --map-base-url <url:folder>    maps all schema references from base url to local folder
-  -h, --help                     display help for command
-```
-
-<details>
-  <summary>Click here to read more about supported values for the <code>&lt;template&gt;</code> parameter.</summary>
-  <br>
-  Templates are installable npm packages. Therefore, the value of <code>&lt;template&gt;</code> can be anything supported by <code>npm install</code>. Here's a summary of the possibilities:
-  <br><br>
-  <pre><code>
-  npm install [&lt;@scope&gt;/]&lt;name&gt;
-  npm install [&lt;@scope&gt;/]&lt;name&gt;@&lt;tag&gt;
-  npm install [&lt;@scope&gt;/]&lt;name&gt;@&lt;version&gt;
-  npm install [&lt;@scope&gt;/]&lt;name&gt;@&lt;version range&gt;
-  npm install &lt;git-host&gt;:&lt;git-user&gt;/&lt;repo-name&gt;
-  npm install &lt;git repo url&gt;
-  npm install &lt;tarball file&gt;
-  npm install &lt;tarball url&gt;
-  npm install &lt;folder&gt;</code></pre>
-</details>
-<br>
+### CLI installation
+Learn to install the AsyncAPI CLI from the [installation guide](installation-guide.md).
 
-### Global templates installed with yarn or npm
+### CLI usage 
 
-You can preinstall templates globally. The generator first tries to locate template in local dependencies and then in location where global packages are installed.
-
-```bash
-npm install -g @asyncapi/html-template@0.16.0
-ag asyncapi.yaml @asyncapi/html-template
-# The generator uses template in version 0.16.0 and not latest
-```
-
-### CLI usage examples
-
-**The shortest possible syntax:**
-```bash
-ag asyncapi.yaml @asyncapi/html-template
-```
-
-**Generating from a URL:**
-```bash
-ag https://bit.ly/asyncapi @asyncapi/html-template
-```
-
-**Specify where to put the result:**
-```bash
-ag asyncapi.yaml @asyncapi/html-template -o ./docs
-```
-
-**Passing parameters to templates:**
-```bash
-ag asyncapi.yaml @asyncapi/html-template -o ./docs -p title='Hello from param'
-```
-
-In the template you can use it like this: ` {{ params.title }}`
-
-**Disabling the hooks:**
-```bash
-ag asyncapi.yaml @asyncapi/html-template -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.
-
-**Installing the template from a folder:**
-```bash
-ag asyncapi.yaml ~/my-template
-```
-
-It creates a symbolic link to the target directory (`~/my-template` in this case).
-
-**Installing the template from a git URL:**
-```bash
-ag asyncapi.yaml https://github.com/asyncapi/html-template.git
-```
-
-**Map schema references from baseUrl to local folder:**
-```bash
-ag test/docs/apiwithref.json @asyncapi/html-template -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.
-
-### CLI usage with Docker
-
-Install [Docker](https://docs.docker.com/get-docker/) first. Thanks to Docker you do not need Node.js even though the generator is written with it.
-
-```bash
-docker run --rm -it \
--v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
--v [GENERATED FILES LOCATION]:/app/output \
-asyncapi/generator [COMMAND HERE]
-
-# Example that you can run inside generator directory after cloning this repository. First you specify mount in location of your AsyncAPI specification file and then you mount in directory where generation result should be saved.
-docker run --rm -it \
--v ${PWD}/test/docs/dummy.yml:/app/asyncapi.yml \
--v ${PWD}/output:/app/output \
-asyncapi/generator -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write
-```
-
-### CLI usage with npx instead of npm
-
-The [npx](https://www.npmjs.com/package/npx) is very useful when you want to run Generator in CI/CD environment. In such a scenario, you do not want to install generator globally and most environments that provide Node.js and npm, also provide npx out of the box.
-
-```bash
-npx -p @asyncapi/generator ag ./asyncapi.yaml @asyncapi/html-template
-```
-
-## Using as a module/package
-
-### Install the module
-
-```bash
-npm install @asyncapi/generator --save
-```
-
-### Example using the module 
-
-Below you can find an example of HTML generation using official `@asyncapi/html-template` template and fetching the spec document from server like `https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml` :
-
-```js
-const path = require('path');
-const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'));
-
-try {
-  await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml');
-  console.log('Done!');
-} catch (e) {
-  console.error(e);
-}
-```
-
-See [API documentation](docs/api.md) for more example and full API reference information.
+Learn more about different ways of using the CLI from the [usage document](usage.md).
 
 ## Generator version vs Template version
 
-The Generator is a tool that you can use to generate whatever you want, taking an AsyncAPI specification file as the input. A template is a tool that uses Generator features and helpers to specify what should be generated.
-
-In other words, a template depends on the Generator and its features. For example, it might work with the latest version of the Generator but not the previous ones. 
-
-The owner of the template specifies in the configuration what version of the Generator it is compatible with:
-```bash
-"generator": ">=0.50.0 <2.0.0",
-```
-
-The Generator doesn't work in case the template is not compatible:
-```bash
-Something went wrong:
-Error: This template is not compatible with the current version of the generator (0.50.0). This template is compatible with the following version range: >=0.60.0 <2.0.0.
-    at Generator.validateTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:678:13)
-    at Generator.loadTemplateConfig (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:663:16)
-    at Generator.generate (/Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/lib/generator.js:146:18)
-    at processTicksAndRejections (internal/process/task_queues.js:97:5)
-    at async /Users/wookiee/.nvm/versions/node/v12.16.1/lib/node_modules/@asyncapi/generator/cli.js:135:7
-```
-
-In case you use Generator CLI and a specific template on production, it is safer to lock to a specific version of the template and the Generator. 
-
-Instead of generating HTML with latest `html-template` and the generator CLI:
-```bash
-npm install -g @asyncapi/generator
-ag asyncapi.yaml @asyncapi/html-template -o ./docs
-```
-
-Generate HTML with the version of the `html-template` and the Generator CLI that you are happy with:
-```bash
-npm install -g @asyncapi/generator@0.50.0
-ag asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs
-```
-
-Before using newer versions of the template, always look at the [changelog](https://github.com/asyncapi/html-template/releases) first. Generator features are not important for you, just make sure to use a version compatible with the template.
+Learn more about versioning from the [versioning document](versioning.md).
 
 ## How to create a template
 

package/docs/README.md

@@ -1,15 +1,18 @@
 Table of Contents
 
 - [Introduction](index.md)
-- [AsyncAPI Specification File](asyncapi-file.md)
+- [AsyncAPI document](asyncapi-document.md)
+- [Installation Guide](installation-guide.md)
+- [Usage](usage.md)
 - [Configuration File](configuration-file.md)
 - [Templates](template.md)
-- [Authoring Templates](authoring-templates.md)
-- [React Render Engine](react-render-engine.md)
-- [Nunjucks Render Engine](nunjucks-render-engine.md)
-- [AsyncAPI Context](asyncapi-context.md)
+- [Authoring templates](authoring-templates.md)
+- [Generator version vs template version](versioning.md)
+- [React render engine](react-render-engine.md)
+- [Nunjucks render engine](nunjucks-render-engine.md)
+- [Template context](template-context.md)
 - [Parser](parser.md)
 - [Hooks](hooks.md)
-- [File Templates](file-templates.md)
-- [TypeScript Support](typescript-support.md)
+- [File templates](file-templates.md)
+- [TypeScript support](typescript-support.md)
 - [Special file names](special-file-names.md)

package/docs/asyncapi-document.md

@@ -0,0 +1,87 @@
+---
+title: "AsyncAPI document"
+weight: 40
+---
+
+The **AsyncAPI document** defines a standard, protocol-agnostic interface that describes message-based or event-driven APIs. The AsyncAPI document allows people or machines communicating with one another, to understand the capabilities of an event-driven API without requiring access to the source code, documentation, or inspecting the network traffic.
+
+This document allows you to define your API structures and formats, including channels the end user can subscribe to and the message formats they receive. 
+
+The documents describing the message-driven API under the AsyncAPI specification are represented as JSON objects and conform to JSON standards. YAML, a superset of JSON, can also be used to represent an API.
+
+> - To learn how to create an AsyncAPI document or refresh your knowledge about the syntax and structure of the AsyncAPI document, check out our [latest specification documentation](https://www.asyncapi.com/docs/reference/specification/latest). 
+> - You can develop, validate, and convert the AsyncAPI document to the latest version or preview your AsyncAPI document in a more readable way using the [AsyncAPI Studio](https://studio.asyncapi.com/).
+
+In the following sections, you'll learn about the inner working of the generator, what happens once the AsyncAPI document is fed to the generator, and how you can access the content of the document in your template.
+
+## AsyncAPI document generation process
+1. The **Generator** receives the **AsyncAPI Document** as input. 
+2. The **Generator** sends to the **[Parser](parser)** the **asyncapiString** is a stringified version of the original **AsyncAPI Document** to validate and parse it.
+3. The **Parser** validates the **AsyncAPI Document** using additional schema-related plugins, either the OpenAPI schema, RAML data types, or Avro schema. 
+4. If the **Parser** determines that the **AsyncAPI Document** is valid, it manipulates the original JSON/YAML document and provides a set of helper functions in return, bundling them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument). 
+5. At this point, the **Generator** passes the **originalAsyncAPI** and the **asyncapi** which make up part of the **[Template Context](asyncapi-context)** to the **Render Engine**. 
+6. The **Template Context** is accessible to the template files that are passed to either the [react](react-render-engine) or [nunjucks](nunjucks-render-engine) **Render Engines**.
+   
+``` mermaid
+graph LR
+    A[Template Context]
+    B{Generator}
+    C[Parser]
+    D[Render Engine]
+    E[AsyncAPI Document] --> B
+  subgraph Generator
+    B -->| asyncapiString | C
+    C --> | asyncapi -> AsyncAPIDocument type | A
+    B--> | originalAsyncAPI -> Stringified document | A
+    A --> D
+  end
+  ```
+The AsyncAPI document's content is accessible to you while writing your template in two distinct ways:
+* The `originalAsyncAPI`, which is a stringified version of the AsyncAPI document provided as input, without any modifications.
+* The `asyncapi` (`AsyncAPIDocument`) which is an object with a set of helper functions, that comes as a result of the `Parser` manipulating the `originalAyncAPI` .The `asyncapi` functions make it easier to access the contents of AsyncAPI documents in your templates.
+
+In the following sections, you will learn how to use either the **originalAsyncAPI** or the **asyncapi** in your template.
+
+### Method 1: `originalAsyncAPI` and template 
+One way of using the contents of the AsyncAPI document inside your template files is by using its stringified version that reflects the same contents as the AsyncAPI document provided as input to the generator. You can access it directly in your templates using the `originalAsyncAPI` variable. You also access it via the [hooks](hooks) `generator.originalAsyncAPI` because `originalAsyncAPI` is also a part of the generator instance that is passed to hooks.
+
+```js
+//example use case for using a stringified AsyncAPI document inside template hooks
+
+const fs = require('fs');
+const path = require('path');
+
+function createAsyncapiFile(generator) {
+  const asyncapi = generator.originalAsyncAPI;
+  let extension;
+  
+  try {
+    JSON.parse(asyncapi);
+    extension = 'json';
+  } catch (e) {
+    extension = 'yaml';
+  }
+
+  const outputFileName = `asyncapi.${extension}`;
+
+  const asyncapiOutputLocation = path.resolve('./'', outputFileName);
+
+  fs.writeFileSync(asyncapiOutputLocation, asyncapi);
+```
+
+
+### Method 2: `asyncapi` and template
+A major advantage of using `asyncapi` (which is an instance of `AsyncAPIDocument`) is that it enables the developer to easily access the AsyncAPI documents' content by simply invoking a function. 
+
+Once the specification YAML or JSON document is passed as input to the generator, it is passed on to the [Parser](parser) library, which then manipulates the asyncAPI document to a more structured document called the `AsyncAPIDocument`. Once the parser returns the document to the generator, the generator passes it to the render engine. The render engine makes the `AsyncAPIDocument` object accessible to your template through the `asyncapi` variable.
+
+For example, if you want to extract the version of your API from AsyncAPI document, you can do that by calling `asyncapi.version()`. You can say that this one is easy to access from JSON objects, but there are more complex scenarios. For example, to get access to all messages from all channels, you can call `asyncapi.allMessages()` instead of iterating through a complex JSON object on your own.
+
+In the sample code snippet below, notice how you can access the contents of the AsyncAPI document in your template using `asyncapi` variable from the context:
+
+```js
+  const apiName = asyncapi.info().title();
+  const channels = asyncapi.channels();
+```
+
+> To learn about the various instances you can use to access the documents' content, look at the API of the AsyncAPI JavaScript Parser and the structure of [AsyncAPIDocument](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument)

package/docs/authoring-templates.md

@@ -1,5 +1,5 @@
 ---
-title: "Authoring Templates"
+title: "Authoring templates"
 weight: 50
 ---
 

package/docs/configuration-file.md

@@ -1,5 +1,5 @@
 ---
-title: "Configuration File"
+title: "Configuration file"
 weight: 30
 ---
 

package/docs/index.md

@@ -3,4 +3,51 @@ title: "Introduction"
 weight: 10
 ---
 
->This document is under construction.
+The AsyncAPI generator is a tool that generates anything you want using the **[AsyncAPI Document](generator/asyncapi-documents)** and **[Template](generator/template)** that are supplied as inputs to the AsyncAPI CLI. The generator was built with extensibility in mind; you can use the generator to generate anything you want, provided that it can be defined in a template, such as code, diagrams, markdown files, microservices, and applications. A number of [community-maintained templates](https://github.com/search?q=topic%3Aasyncapi+topic%3Agenerator+topic%3Atemplate) are now available for immediate usage.
+
+### Generator use cases 
+- Generation of interactive and understandable API documentation
+- Generation of APIs' client libraries
+- Generation of APIs' boilerplate code
+
+### Generator advantages
+- Quick to setup and easy to use on a regular basis
+- Effortless generation of complex documents
+- Number of community maintained AsyncAPI templates
+
+### Generation process
+1. The **Generator** receives the **[Template](generator/template)** and **[AsyncAPI Document](generator/asyncapi-document)** as inputs. 
+2. The **Generator** sends to the **[Parser](generator/parser)** the **asyncapiString** which is a stringified version of the original **AsyncAPI Document**.
+3. The **Parser** uses additional plugins such as the OpenAPI, RAML, or Avro schemas to validate custom schemas of message payloads defined in the **AsyncAPI Document**.
+4. If the **Parser** determines that the original **AsyncAPI Document** is valid, it manipulates the document and returns a set of helper functions and properties and bundles them together into an **asyncapi** variable that is an instance of [**AsyncAPIDocument**](https://github.com/asyncapi/parser-js/blob/master/API.md#module_@asyncapi/parser+AsyncAPIDocument). The **asyncapi** helper functions make it easier to access the contents of the AsyncAPI Document.
+5. At this point, the **Generator** passes the **[asyncapi](generator/asyncapi-document#method-2-asyncapi-and-template)**, the **[originalAsyncAPI](generator/asyncapi-document#method-1-originalasyncapi-and-template)**, and the **params** which collectively make up the **[Template Context](generator/asyncapi-context)** to the **Render Engine**. 
+6. AsyncAPI has two **Render Engines**([react](generator/react-render-engine) and [nunjucks](generator/nunjucks-render-engine). Depending on which one you've specified in your `package.json`, the **Generator** knows the right **Render Engine** to pass both the **Template Files** and the **Template Context**.
+7. Once the **Render Engine** receives the **Template Files** and the **Template Context**, it injects all the dynamic values in your react or nunjucks based **Template Files** using the **Template Context**. As a result, the **Render Engine** generates **markdown**, **pdf**, **boilerplate code**, and **anything else** you specified to be generated as output.
+
+> You can generate anything you want using the generator as long as it can be defined in a **Template**.
+
+The diagram below depicts the entire process of passing the **Template** and **AsyncAPI Document** to the AsyncAPI generator tool, how the generator uses these inputs to generate the desired output, and example outputs you can get from the render engine.
+
+``` mermaid
+graph LR
+    A[Template Context]
+    B{Generator}
+    C[Parser]
+    D[Render Engine]
+    E[AsyncAPI Document] --> B
+    F[Template] --> B
+  subgraph Generator Library
+    B -->| asyncapiString | C
+    C --> | asyncapi | A
+    B--> | originalAsyncAPI | A
+    B--> | params | A
+    A --> D
+    B --> | Template Files | D
+  end
+  D --> O[HTML]
+  D --> M[Markdown]
+  D --> N[Node.js]
+  D --> J[Java Spring Boot]
+  D --> K[Anything else]
+  ```
+**`params`** are template-specific options passed to the `asyncapi generate fromTemplate` CLI command to customize the generated output.

package/docs/installation-guide.md

@@ -0,0 +1,81 @@
+---
+title: "Installation guide"
+weight: 20
+---
+
+You can use the generator library to generate whatever you want in your event-driven architecture apps. Find your preferred method below:
+- [AsyncAPI CLI](#asyncapi-cli)
+- [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 v12.16 and higher
+2. Npm v6.13.7 and higher
+   
+To verify the versions of Node and Npm you have, run the following command on your terminal:
+```
+npm -v
+```
+```
+node -v
+```
+
+If you don't have either Node or Npm installed, use the [official node.js installer](https://nodejs.org/en/download/).
+
+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.
+
+### 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 generator CLI, check the template's `package.json` for the version of the generator 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).
+
+## 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`.
+
+> Don't include the `-g` flag in the installation command above since you're not installing the generator library globally but in your Node.js project.

package/docs/nunjucks-render-engine.md

@@ -1,5 +1,5 @@
 ---
-title: "Nunjucks Render Engine"
+title: "Nunjucks render engine"
 weight: 70
 ---
 

package/docs/react-render-engine.md

@@ -1,5 +1,5 @@
 ---
-title: "React Render Engine"
+title: "React render engine"
 weight: 60
 ---
 

package/docs/template-context.md

@@ -0,0 +1,41 @@
+---
+title: "Template context"
+weight: 60
+---
+
+While using the generator tool, you may want dynamic values populated to your templates and rendered in the output. The generator can achieve that using the **template context**.
+The **template context** allows you to access the contents of the [AsyncAPI document](asyncapi-document.md) and inject dynamic values to the template files passed to the asyncAPI CLI during the generation process. The render engine then displays these dynamically assigned values in the output.
+
+## Generation process
+1. The **Generator** receives **Template** and **params** as input.
+2. The **Generator** sends to the **Parser** the **asyncapiString** which is a stringified version of the original **AsyncAPI document**. 
+3. The **Parser** validates the format of the **asyncapiString** using OpenAPI, RAML, or Avro schemas.
+4. If the **asyncapiString** is valid, the **parser** manipulates it, returns a set of helper functions and properties, and bundles them into an **asyncapi** variable. The **asyncapi** variable is an instance of the **AsyncAPI document**. The helper functions and properties make it easier to access the contents of the **AsyncAPI document** in the template.
+5. The **Generator** then passes the **params**, which are template-specific options used to customize the output, the **Template files**, and the **asyncapi** which collectively make up the **Template Context**.
+6. The **Template Context** is then passed to the **Render Engine**. The **Render Engine** then injects all the dynamic values from the **Template Context** into the **Template files**.
+   
+``` mermaid
+graph LR
+    A[Template Context]
+    B{Generator}
+    C[Parser]
+    D[Render Engine]
+    E[Template] --> B
+    F[Params] --> B
+    G[AsyncAPI Document] --> B
+  subgraph Generator
+    B -->| params | A
+    B--> | asyncapiString| C
+    B -->| originalAsyncAPI | A
+    C --> | asyncapi -> AsyncAPIDocument type | A
+    B--> | Template Files | D
+    A --> D
+  end
+```
+
+## Template context
+The extra context passed to the render engine during the generation process and made accessible in the templates includes:
+
+- **`originalAsyncAPI`** is a stringified version of the original AsyncAPI document that the user passed to the Generator.
+- **`asyncapi`** is a parsed AsyncAPI document with helper functions and properties. You should use it to access document contents e.g `asyncapi.title`.
+- **`params`** is an object with all the parameters passed to the Generator by the user.

package/docs/typescript-support.md

@@ -1,5 +1,5 @@
 ---
-title: "TypeScript Support"
+title: "TypeScript support"
 weight: 120
 ---
 

package/docs/usage.md

@@ -0,0 +1,151 @@
+---
+title: "Usage"
+weight: 30
+---
+
+There are two ways to use the generator:
+- [Generator CLI](#generator-cli)
+- [Generator library](#using-as-a-modulepackage)
+
+## Generator CLI
+```bash
+Usage: asyncapi generate fromTemplate <asyncapi> <template> [<options>]
+
+- <asyncapi>: Local path or URL pointing to AsyncAPI document for example https://bit.ly/asyncapi
+- <template>: Name of the generator template like for example @asyncapi/html-template or https://github.com/asyncapi/html-template
+
+- <options>:
+  -V, --version                  output the generator version
+  -d, --disable-hook [hooks...]  disable a specific hook type or hooks from a given hook type
+  --debug                        enable more specific errors in the console
+  -i, --install                  install the template and its dependencies (defaults to false)
+  -n, --no-overwrite <glob>      glob or path of the file(s) to skip when regenerating
+  -o, --output <outputDir>       directory to put the generated files (defaults to current directory)
+  -p, --param <name=value>       additional parameters to pass to templates
+  --force-write                  force writing of the generated files to a given directory even if it is a Git repository with unstaged files or not empty dir (defaults to false)
+  --watch-template               watches the template directory and the AsyncAPI document, and re-generates the files when changes occur. Ignores the output directory. This flag should be used only for template development.
+  --map-base-url <url:folder>    maps all schema references from base URL to local folder
+  -h, --help                     display help for command
+```
+
+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:
+```
+npm install [<@scope>/]<name>
+npm install [<@scope>/]<name>@<tag>
+npm install [<@scope>/]<name>@<version>
+npm install [<@scope>/]<name>@<version range>
+npm install <git-host>:<git-user>/<repo-name>
+npm install <git repo url>
+npm install <tarball file>
+npm install <tarball url>
+npm install <folder>
+```
+
+### Global templates installed with `yarn` or `npm`
+
+You can preinstall templates globally before installing the generator CLI. The generator first tries to locate the template in local dependencies; if absent it checks where the global generator packages are installed.
+
+```bash
+npm install -g @asyncapi/html-template@0.16.0
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
+# The generator uses html-template version 0.16.0 and not the latest version.
+```
+
+### CLI usage examples
+
+**The shortest possible syntax:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template
+```
+
+**Generating from a URL:**
+```bash
+asyncapi generate fromTemplate https://bit.ly/asyncapi @asyncapi/html-template
+```
+
+**Specify where to put the result:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -o ./docs
+```
+
+**Passing parameters to templates:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template -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
+```
+
+The generator skips all hooks of the `generate:before` type and `foo`, `bar` hooks of the `generate:after` type.
+
+**Installing the template from a folder:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml ~/my-template
+```
+
+It creates a symbolic link to the target directory (`~/my-template` in this case).
+
+**Installing the template from a git URL:**
+```bash
+asyncapi generate fromTemplate asyncapi.yaml https://github.com/asyncapi/html-template.git
+```
+
+**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/
+```
+
+The parameter `--map-base-url` maps external schema references to local folders.
+
+### CLI usage with Docker
+
+When using our docker image that we regularly update, you don't need to install Node.js or Npm, even though the generator is written with it since the Docker image has the generator installed.
+
+Install [Docker](https://docs.docker.com/get-docker/) first, then use docker to pull and run the image using the following command:
+
+```bash
+docker run --rm -it \
+-v [ASYNCAPI SPEC FILE LOCATION]:/app/asyncapi.yml \
+-v [GENERATED FILES LOCATION]:/app/output \
+asyncapi/generator [COMMAND HERE]
+
+# Example that you can run inside the generator 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 \
+-v ${PWD}/test/docs/dummy.yml:/app/asyncapi.yml \
+-v ${PWD}/output:/app/output \
+asyncapi/generator -o /app/output /app/asyncapi.yml @asyncapi/html-template --force-write
+```
+
+### CLI usage with `npx` instead of `npm`
+
+[npx](https://www.npmjs.com/package/npx) is very useful when you want to run the generator in a CI/CD environment. In such a scenario, do not install the generator globally because most environments that provide Node.js and Npm, also provide npx out of the box. 
+
+Use the following npx command on your terminal:
+
+```bash
+npx -p @asyncapi/cli asyncapi generate fromTemplate ./asyncapi.yaml @asyncapi/html-template
+```
+
+## Using as a module/package
+Once you install the generator in your project, you can use it to generate whatever you want. The following code snippet is an example of HTML generation using the official `@asyncapi/html-template` template and fetching the spec document from the server using:
+```
+https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml
+```
+
+```js
+const path = require('path');
+const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'));
+
+try {
+  await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml');
+  console.log('Done!');
+} catch (e) {
+  console.error(e);
+}
+```
+
+See the [API documentation](api.md) for more examples and full API reference information.

package/docs/versioning.md

@@ -0,0 +1,31 @@
+---
+title: "Generator version vs template version"
+weight: 60
+---
+
+The generator tool generates whatever you want, as long as it can be defined in a template based on the [AsyncAPI document](asyncapi-document). On the other hand, a **template** is a file or group of files that specify the kind of output you expect from using the generator's features. For example, you may want to use the [NodeJS template](https://github.com/asyncapi/nodejs-template) to generate boilerplate code for your message-based APIs.
+
+Templates are dependent on the generators' features. For example, the template you want to use may be compatible with the latest generator version but incompatible with the previous versions. Check the configuration file or ReadME of the template to see the version of the generator it supports. The generator has an `isTemplateCompatible` function that checks if the template is compatible with the version of the generator you want to use. If the template isn't compatible, you will see a terminal error output similar to the following:
+```
+Something went wrong:
+Error: This template is not compatible with the current version of the generator (${generatorVersion}). This template is compatible with the following version range: ${generator}.`)
+```
+
+> Use the following command to check the version of the AsyncAPI CLI you have installed;  `asyncapi --version`
+
+It is better to lock a specific version of the template and the generator if you plan to use the AsyncAPI CLI and a particular template in production. The differences between using the version of the AsyncAPI CLI you have installed and locking a certain version on production are demonstrated in the following code snippets.
+
+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
+```
+
+Generate HTML using a particular version of the AsyncAPI CLI using the html-template.
+
+```
+npm install -g @asyncapi/cli@0.20.0
+asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@0.7.0 -o ./docs
+```
+
+> Before using newer versions of the template, always look at the [changelog](https://github.com/asyncapi/html-template/releases) first. If the generator's features are not important to you, just make sure to use a version compatible with your template.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asyncapi/generator",
-  "version": "1.9.12",
+  "version": "1.9.14",
   "description": "The AsyncAPI generator. It can generate documentation, code, anything!",
   "main": "./lib/generator.js",
   "bin": {
@@ -50,7 +50,7 @@
     "@asyncapi/avro-schema-parser": "^1.1.0",
     "@asyncapi/generator-react-sdk": "^0.2.23",
     "@asyncapi/openapi-schema-parser": "^2.0.1",
-    "@asyncapi/parser": "^1.17.0",
+    "@asyncapi/parser": "^1.17.1",
     "@asyncapi/raml-dt-schema-parser": "^2.0.1",
     "@npmcli/arborist": "^2.2.4",
     "ajv": "^6.10.2",
@@ -73,8 +73,8 @@
     "semver": "^7.3.2",
     "simple-git": "^3.3.0",
     "source-map-support": "^0.5.19",
-    "ts-node": "^9.1.1",
-    "typescript": "^4.2.2"
+    "ts-node": "^10.9.1",
+    "typescript": "^4.9.3"
   },
   "devDependencies": {
     "eslint": "^6.8.0",

package/docs/asyncapi-context.md

@@ -1,6 +0,0 @@
----
-title: "AsyncAPI Context"
-weight: 80
----
-
->This document is under construction.

package/docs/asyncapi-file.md

@@ -1,6 +0,0 @@
----
-title: "AsyncAPI Specification File"
-weight: 20
----
-
->This document is under construction.