@asyncapi/generator 1.9.13 → 1.9.15

package/docs/api.md

@@ -1,3 +1,10 @@
+---
+title: Library API
+weight: 75
+---
+
+Reference API documentation for AsyncAPI Generator library.
+
 <a name="Generator"></a>
 
 ## Generator
@@ -6,49 +13,49 @@
 * [Generator](#Generator)
     * [new Generator(templateName, targetDir, options)](#new_Generator_new)
     * _instance_
-        * [.templateName](#Generator+templateName) : <code>String</code>
-        * [.targetDir](#Generator+targetDir) : <code>String</code>
-        * [.entrypoint](#Generator+entrypoint) : <code>String</code>
-        * [.noOverwriteGlobs](#Generator+noOverwriteGlobs) : <code>Array.&lt;String&gt;</code>
-        * [.disabledHooks](#Generator+disabledHooks) : <code>Object.&lt;String, (Boolean\|String\|Array.&lt;String&gt;)&gt;</code>
-        * [.output](#Generator+output) : <code>String</code>
-        * [.forceWrite](#Generator+forceWrite) : <code>Boolean</code>
-        * [.debug](#Generator+debug) : <code>Boolean</code>
-        * [.install](#Generator+install) : <code>Boolean</code>
-        * [.templateConfig](#Generator+templateConfig) : <code>Object</code>
-        * [.hooks](#Generator+hooks) : <code>Object</code>
-        * [.mapBaseUrlToFolder](#Generator+mapBaseUrlToFolder) : <code>Object</code>
-        * [.templateParams](#Generator+templateParams) : <code>Object</code>
-        * [.originalAsyncAPI](#Generator+originalAsyncAPI) : <code>String</code>
-        * [.generate(asyncapiDocument)](#Generator+generate) ⇒ <code>Promise</code>
+        * [.templateName](#Generator+templateName) : `String`
+        * [.targetDir](#Generator+targetDir) : `String`
+        * [.entrypoint](#Generator+entrypoint) : `String`
+        * [.noOverwriteGlobs](#Generator+noOverwriteGlobs) : `Array.<String>`
+        * [.disabledHooks](#Generator+disabledHooks) : `Object.<String, (Boolean|String|Array.<String>)>`
+        * [.output](#Generator+output) : `String`
+        * [.forceWrite](#Generator+forceWrite) : `Boolean`
+        * [.debug](#Generator+debug) : `Boolean`
+        * [.install](#Generator+install) : `Boolean`
+        * [.templateConfig](#Generator+templateConfig) : `Object`
+        * [.hooks](#Generator+hooks) : `Object`
+        * [.mapBaseUrlToFolder](#Generator+mapBaseUrlToFolder) : `Object`
+        * [.templateParams](#Generator+templateParams) : `Object`
+        * [.originalAsyncAPI](#Generator+originalAsyncAPI) : `String`
+        * [.generate(asyncapiDocument)](#Generator+generate) ⇒ `Promise`
         * [.configureTemplate()](#Generator+configureTemplate)
-        * [.generateFromString(asyncapiString, [parserOptions])](#Generator+generateFromString) ⇒ <code>Promise</code>
-        * [.generateFromURL(asyncapiURL)](#Generator+generateFromURL) ⇒ <code>Promise</code>
-        * [.generateFromFile(asyncapiFile)](#Generator+generateFromFile) ⇒ <code>Promise</code>
+        * [.generateFromString(asyncapiString, [parserOptions])](#Generator+generateFromString) ⇒ `Promise`
+        * [.generateFromURL(asyncapiURL)](#Generator+generateFromURL) ⇒ `Promise`
+        * [.generateFromFile(asyncapiFile)](#Generator+generateFromFile) ⇒ `Promise`
         * [.installTemplate([force])](#Generator+installTemplate)
     * _static_
-        * [.getTemplateFile(templateName, filePath, [templatesDir])](#Generator.getTemplateFile) ⇒ <code>Promise</code>
+        * [.getTemplateFile(templateName, filePath, [templatesDir])](#Generator.getTemplateFile) ⇒ `Promise`
+
 
 <a name="new_Generator_new"></a>
 
-### new Generator(templateName, targetDir, options)
+### new Generator
 Instantiates a new Generator object.
 
-
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| templateName | <code>String</code> |  | Name of the template to generate. |
-| targetDir | <code>String</code> |  | Path to the directory where the files will be generated. |
-| options | <code>Object</code> |  |  |
-| [options.templateParams] | <code>String</code> |  | Optional parameters to pass to the template. Each template define their own params. |
-| [options.entrypoint] | <code>String</code> |  | Name of the file to use as the entry point for the rendering process. Use in case you want to use only a specific template file. Note: this potentially avoids rendering every file in the template. |
-| [options.noOverwriteGlobs] | <code>Array.&lt;String&gt;</code> |  | List of globs to skip when regenerating the template. |
-| [options.disabledHooks] | <code>Object.&lt;String, (Boolean\|String\|Array.&lt;String&gt;)&gt;</code> |  | Object with hooks to disable. The key is a hook type. If key has "true" value, then the generator skips all hooks from the given type. If the value associated with a key is a string with the name of a single hook, then the generator skips only this single hook name. If the value associated with a key is an array of strings, then the generator skips only hooks from the array. |
-| [options.output] | <code>String</code> | <code>&#x27;fs&#x27;</code> | Type of output. Can be either 'fs' (default) or 'string'. Only available when entrypoint is set. |
-| [options.forceWrite] | <code>Boolean</code> | <code>false</code> | Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false. |
-| [options.install] | <code>Boolean</code> | <code>false</code> | Install the template and its dependencies, even when the template has already been installed. |
-| [options.debug] | <code>Boolean</code> | <code>false</code> | Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive. |
-| [options.mapBaseUrlToFolder] | <code>Object.&lt;String, String&gt;</code> |  | Optional parameter to map schema references from a base url to a local base folder e.g. url=https://schema.example.com/crm/  folder=./test/docs/ . |
+**Params**
+
+- templateName `String` - Name of the template to generate.
+- targetDir `String` - Path to the directory where the files will be generated.
+- options `Object`
+    - [.templateParams] `String` - Optional parameters to pass to the template. Each template define their own params.
+    - [.entrypoint] `String` - Name of the file to use as the entry point for the rendering process. Use in case you want to use only a specific template file. Note: this potentially avoids rendering every file in the template.
+    - [.noOverwriteGlobs] `Array.<String>` - List of globs to skip when regenerating the template.
+    - [.disabledHooks] `Object.<String, (Boolean|String|Array.<String>)>` - Object with hooks to disable. The key is a hook type. If key has "true" value, then the generator skips all hooks from the given type. If the value associated with a key is a string with the name of a single hook, then the generator skips only this single hook name. If the value associated with a key is an array of strings, then the generator skips only hooks from the array.
+    - [.output] `String` ` = 'fs'` - Type of output. Can be either 'fs' (default) or 'string'. Only available when entrypoint is set.
+    - [.forceWrite] `Boolean` ` = false` - Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.
+    - [.install] `Boolean` ` = false` - Install the template and its dependencies, even when the template has already been installed.
+    - [.debug] `Boolean` ` = false` - Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.
+    - [.mapBaseUrlToFolder] `Object.<String, String>` - Optional parameter to map schema references from a base url to a local base folder e.g. url=https://schema.example.com/crm/  folder=./test/docs/ .
 
 **Example**  
 ```js
@@ -64,100 +71,114 @@ const generator = new Generator('@asyncapi/html-template', path.resolve(__dirnam
   }
 });
 ```
+
 <a name="Generator+templateName"></a>
 
-### generator.templateName : <code>String</code>
+* generator.templateName : `String`** :
 Name of the template to generate.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+targetDir"></a>
 
-### generator.targetDir : <code>String</code>
+* generator.targetDir : `String`** :
 Path to the directory where the files will be generated.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+entrypoint"></a>
 
-### generator.entrypoint : <code>String</code>
+* generator.entrypoint : `String`** :
 Name of the file to use as the entry point for the rendering process. Use in case you want to use only a specific template file. Note: this potentially avoids rendering every file in the template.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+noOverwriteGlobs"></a>
 
-### generator.noOverwriteGlobs : <code>Array.&lt;String&gt;</code>
+* generator.noOverwriteGlobs : `Array.<String>`** :
 List of globs to skip when regenerating the template.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+disabledHooks"></a>
 
-### generator.disabledHooks : <code>Object.&lt;String, (Boolean\|String\|Array.&lt;String&gt;)&gt;</code>
+* generator.disabledHooks : `Object.<String, (Boolean|String|Array.<String>)>`** :
 Object with hooks to disable. The key is a hook type. If key has "true" value, then the generator skips all hooks from the given type. If the value associated with a key is a string with the name of a single hook, then the generator skips only this single hook name. If the value associated with a key is an array of strings, then the generator skips only hooks from the array.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+output"></a>
 
-### generator.output : <code>String</code>
+* generator.output : `String`** :
 Type of output. Can be either 'fs' (default) or 'string'. Only available when entrypoint is set.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+forceWrite"></a>
 
-### generator.forceWrite : <code>Boolean</code>
+* generator.forceWrite : `Boolean`** :
 Force writing of the generated files to given directory even if it is a git repo with unstaged files or not empty dir. Default is set to false.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+debug"></a>
 
-### generator.debug : <code>Boolean</code>
+* generator.debug : `Boolean`** :
 Enable more specific errors in the console. At the moment it only shows specific errors about filters. Keep in mind that as a result errors about template are less descriptive.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+install"></a>
 
-### generator.install : <code>Boolean</code>
+* generator.install : `Boolean`** :
 Install the template and its dependencies, even when the template has already been installed.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+templateConfig"></a>
 
-### generator.templateConfig : <code>Object</code>
+* generator.templateConfig : `Object`** :
 The template configuration.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+hooks"></a>
 
-### generator.hooks : <code>Object</code>
+* generator.hooks : `Object`** :
 Hooks object with hooks functions grouped by the hook type.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+mapBaseUrlToFolder"></a>
 
-### generator.mapBaseUrlToFolder : <code>Object</code>
+* generator.mapBaseUrlToFolder : `Object`** :
 Maps schema URL to folder.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+templateParams"></a>
 
-### generator.templateParams : <code>Object</code>
+* generator.templateParams : `Object`** :
 The template parameters. The structure for this object is based on each individual template.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+originalAsyncAPI"></a>
 
-### generator.originalAsyncAPI : <code>String</code>
+* generator.originalAsyncAPI : `String`** :
 AsyncAPI string to use as a source.
 
-**Kind**: instance property of [<code>Generator</code>](#Generator)  
+**Kind**: instance property of [`Generator`](#Generator)  
+
 <a name="Generator+generate"></a>
 
-### generator.generate(asyncapiDocument) ⇒ <code>Promise</code>
+### generator.generate
 Generates files from a given template and an AsyncAPIDocument object.
 
-**Kind**: instance method of [<code>Generator</code>](#Generator)  
+**Kind**: instance method of [`Generator`](#Generator)  
+**Params**
 
-| Param | Type | Description |
-| --- | --- | --- |
-| asyncapiDocument | <code>AsyncAPIDocument</code> | AsyncAPIDocument object to use as source. |
+- asyncapiDocument `AsyncAPIDocument` - AsyncAPIDocument object to use as source.
 
 **Example**  
 ```js
@@ -177,23 +198,24 @@ try {
   console.error(e);
 }
 ```
+
 <a name="Generator+configureTemplate"></a>
 
-### generator.configureTemplate()
+* generator.configureTemplate()** :
 Configure the templates based the desired renderer.
 
-**Kind**: instance method of [<code>Generator</code>](#Generator)  
+**Kind**: instance method of [`Generator`](#Generator)  
+
 <a name="Generator+generateFromString"></a>
 
-### generator.generateFromString(asyncapiString, [parserOptions]) ⇒ <code>Promise</code>
+### generator.generateFromString
 Generates files from a given template and AsyncAPI string.
 
-**Kind**: instance method of [<code>Generator</code>](#Generator)  
+**Kind**: instance method of [`Generator`](#Generator)  
+**Params**
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| asyncapiString | <code>String</code> |  | AsyncAPI string to use as source. |
-| [parserOptions] | <code>Object</code> | <code>{}</code> | AsyncAPI parser options. Check out [@asyncapi/parser](https://www.github.com/asyncapi/parser-js) for more information. |
+- asyncapiString `String` - AsyncAPI string to use as source.
+- [parserOptions] `Object` ` = {}` - AsyncAPI parser options. Check out [@asyncapi/parser](https://www.github.com/asyncapi/parser-js) for more information.
 
 **Example**  
 ```js
@@ -228,16 +250,16 @@ try {
   console.error(e);
 }
 ```
+
 <a name="Generator+generateFromURL"></a>
 
-### generator.generateFromURL(asyncapiURL) ⇒ <code>Promise</code>
+### generator.generateFromURL
 Generates files from a given template and AsyncAPI file stored on external server.
 
-**Kind**: instance method of [<code>Generator</code>](#Generator)  
+**Kind**: instance method of [`Generator`](#Generator)  
+**Params**
 
-| Param | Type | Description |
-| --- | --- | --- |
-| asyncapiURL | <code>String</code> | Link to AsyncAPI file |
+- asyncapiURL `String` - Link to AsyncAPI file
 
 **Example**  
 ```js
@@ -257,16 +279,16 @@ try {
   console.error(e);
 }
 ```
+
 <a name="Generator+generateFromFile"></a>
 
-### generator.generateFromFile(asyncapiFile) ⇒ <code>Promise</code>
+### generator.generateFromFile
 Generates files from a given template and AsyncAPI file.
 
-**Kind**: instance method of [<code>Generator</code>](#Generator)  
+**Kind**: instance method of [`Generator`](#Generator)  
+**Params**
 
-| Param | Type | Description |
-| --- | --- | --- |
-| asyncapiFile | <code>String</code> | AsyncAPI file to use as source. |
+- asyncapiFile `String` - AsyncAPI file to use as source.
 
 **Example**  
 ```js
@@ -286,37 +308,37 @@ try {
   console.error(e);
 }
 ```
+
 <a name="Generator+installTemplate"></a>
 
-### generator.installTemplate([force])
+### generator.installTemplate
 Downloads and installs a template and its dependencies
 
-**Kind**: instance method of [<code>Generator</code>](#Generator)  
+**Kind**: instance method of [`Generator`](#Generator)  
+**Params**
+
+- [force] `Boolean` ` = false` - Whether to force installation (and skip cache) or not.
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| [force] | <code>Boolean</code> | <code>false</code> | Whether to force installation (and skip cache) or not. |
 
 <a name="Generator.getTemplateFile"></a>
 
-### Generator.getTemplateFile(templateName, filePath, [templatesDir]) ⇒ <code>Promise</code>
+### Generator.getTemplateFile
 Returns the content of a given template file.
 
-**Kind**: static method of [<code>Generator</code>](#Generator)  
+**Kind**: static method of [`Generator`](#Generator)  
+**Params**
 
-| Param | Type | Default | Description |
-| --- | --- | --- | --- |
-| templateName | <code>String</code> |  | Name of the template to generate. |
-| filePath | <code>String</code> |  | Path to the file to render. Relative to the template directory. |
-| [templatesDir] | <code>String</code> | <code>DEFAULT_TEMPLATES_DIR</code> | Path to the directory where the templates are installed. |
+- templateName `String` - Name of the template to generate.
+- filePath `String` - Path to the file to render. Relative to the template directory.
+- [templatesDir] `String` ` = DEFAULT_TEMPLATES_DIR` - Path to the directory where the templates are installed.
 
 **Example**  
 ```js
-const Generator = require('asyncapi-generator');
+const Generator = require('@asyncapi/generator');
 const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html');
 ```
 **Example** *(Using a custom &#x60;templatesDir&#x60;)*  
 ```js
-const Generator = require('asyncapi-generator');
+const Generator = require('@asyncapi/generator');
 const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html', '~/my-templates');
 ```

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/configuration-file.md

@@ -1,6 +1,6 @@
 ---
-title: "Configuration File"
-weight: 30
+title: "Configuration file"
+weight: 90
 ---
 
 The `generator` property from `package.json` file must contain a JSON object that may have the following information:
@@ -17,7 +17,7 @@ The `generator` property from `package.json` file must contain a JSON object tha
 |`conditionalFiles[filePath].subject`| String | The `subject` is a [JMESPath](http://jmespath.org/) query to grab the value you want to apply the condition to. It queries an object with the whole AsyncAPI document and, when specified, the given server. The object looks like this: `{ asyncapi: { ... }, server: { ... } }`. If the template supports `server` parameter, you can access server details like for example protocol this way: `server.protocol`. During validation with `conditionalFiles` only the server that template user selected is available in the specification file. For more information about `server` parameter [read about special parameters](#special-parameters).
 |`conditionalFiles[filePath].validation`| Object | The `validation` is a JSON Schema Draft 07 object. This JSON Schema definition will be applied to the JSON value resulting from the `subject` query. If validation doesn't have errors, the condition is met, and therefore the given file will be rendered. Otherwise, the file is ignored. Check [JSON Schema Validation](https://json-schema.org/draft-07/json-schema-validation.html#rfc.section.6) document for a list of all possible validation keywords.
 |`nonRenderableFiles`| [String] | A list of file paths or [globs](https://en.wikipedia.org/wiki/Glob_(programming)) that must be copied "as-is" to the target directory, i.e., without performing any rendering process. This is useful when you want to copy binary files.
-|`generator`| [String] | A string representing the Generator version-range the template is compatible with. This value must follow the [semver](https://nodejs.dev/learn/semantic-versioning-using-npm) syntax. E.g., `>=1.0.0`, `>=1.0.0 <=2.0.0`, `~1.0.0`, `^1.0.0`, `1.0.0`, etc. [Read more about semver](https://docs.npmjs.com/about-semantic-versioning).
+|`generator`| [String] | A string representing the generator version-range the template is compatible with. This value must follow the [semver](https://nodejs.dev/learn/semantic-versioning-using-npm) syntax. E.g., `>=1.0.0`, `>=1.0.0 <=2.0.0`, `~1.0.0`, `^1.0.0`, `1.0.0`, etc. [Read more about semver](https://docs.npmjs.com/about-semantic-versioning).
 |`filters`| [String] | A list of modules containing functions that can be used as Nunjucks filters. In case of external modules, remember they need to be added as a dependency in `package.json` of your template.
 |`hooks`| Object[String, String] or Object[String, Array[String]] | A list of modules containing hooks, except for the ones you keep locally in your template in default location. For each module you must specify the exact name of the hook that should be used in the template. For a single hook you can specify it as a string, for more you must pass an array of strings. In case of external modules, remember they need to be added as a dependency in `package.json` of your template.
 

package/docs/file-templates.md

@@ -1,6 +1,6 @@
 ---
 title: "File templates"
-weight: 110
+weight: 140
 ---
 
 It is possible to generate files for each specific object in your AsyncAPI documentation. For example, you can specify a filename like `$$channel$$.js` to generate a file for each channel defined in your AsyncAPI. The following file-template names and extra variables in them are available:

package/docs/hooks.md

@@ -1,6 +1,6 @@
 ---
 title: "Hooks"
-weight: 100
+weight: 130
 ---
 
 Hooks are functions called by the generator on a specific moment in the generation process. Hooks can be anonymous functions but you can also add function names. These hooks can have arguments provided to them or being expected to return a value.

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.