docs: add installation guide

README.md

@@ -71,28 +71,8 @@ Install both packages using [official installer](https://nodejs.org/en/download/
 
 ## 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 installation
+Learn to install the AsyncAPI CLI from the [installation guide](installation-guide.md).
 
 ### CLI usage
 
@@ -247,41 +227,7 @@ See [API documentation](docs/api.md) for more example and full API reference inf
 
 ## 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
 

docs/README.md

@@ -5,6 +5,7 @@ Table of Contents
 - [Configuration File](configuration-file.md)
 - [Templates](template.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)
 - [AsyncAPI Context](asyncapi-context.md)

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)
+- [Use the Generator Library in Node.js Apps](#2-use-the-generator-library-in-your-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.md). You can generate message-based API boilerplate code, documentation, or anything else you need as long as you specify it in your [template](template.md) 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.md) 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.

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 file](asyncapi-document.md). 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.