diff --git a/README.md b/README.md index 3d09b55be..2a1b969d6 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ There is a large number of templates that are ready to use and are officially su | `@asyncapi/java-spring-template` | Generates Java Spring service | [click here](https://github.com/asyncapi/java-spring-template) | | `@asyncapi/java-spring-cloud-stream-template` | Generates Java Spring Cloud Stream service | [click here](https://github.com/asyncapi/java-spring-cloud-stream-template) | | `@asyncapi/python-paho-template` | Generates Python service that uses Paho library | [click here](https://github.com/asyncapi/python-paho-template) | -| `@asyncapi/html-template` | Generates HTML documentation site | [click here](https://github.com/asyncapi/html-template) | +| `@asyncapi/html-template@3.0.0 --use-new-generator` | Generates HTML documentation site | [click here](https://github.com/asyncapi/html-template) | | `@asyncapi/markdown-template` | Generates documentation in Markdown file | [click here](https://github.com/asyncapi/markdown-template) | | `@asyncapi/ts-nats-template` | Generates TypeScript NATS client | [click here](https://github.com/asyncapi/ts-nats-template/) | | `@asyncapi/go-watermill-template` | Generates Go client using Watermill | [click here](https://github.com/asyncapi/go-watermill-template) | diff --git a/apps/generator/README.md b/apps/generator/README.md index 13f9ba7b3..cc88d50e9 100644 --- a/apps/generator/README.md +++ b/apps/generator/README.md @@ -15,7 +15,7 @@ There is a large number of templates that are ready to use and are officially su | `@asyncapi/java-spring-template` | Generates Java Spring service | [click here](https://github.com/asyncapi/java-spring-template) | | `@asyncapi/java-spring-cloud-stream-template` | Generates Java Spring Cloud Stream service | [click here](https://github.com/asyncapi/java-spring-cloud-stream-template) | | `@asyncapi/python-paho-template` | Generates Python service that uses Paho library | [click here](https://github.com/asyncapi/python-paho-template) | -| `@asyncapi/html-template` | Generates HTML documentation site | [click here](https://github.com/asyncapi/html-template) | +| `@asyncapi/html-template@3.0.0 --use-new-generator` | Generates HTML documentation site | [click here](https://github.com/asyncapi/html-template) | | `@asyncapi/markdown-template` | Generates documentation in Markdown file | [click here](https://github.com/asyncapi/markdown-template) | | `@asyncapi/ts-nats-template` | Generates TypeScript NATS client | [click here](https://github.com/asyncapi/ts-nats-template/) | | `@asyncapi/go-watermill-template` | Generates Go client using Watermill | [click here](https://github.com/asyncapi/go-watermill-template) | diff --git a/apps/generator/docs/api.md b/apps/generator/docs/api.md index 42d7309e5..2bbacf8e5 100644 --- a/apps/generator/docs/api.md +++ b/apps/generator/docs/api.md @@ -75,12 +75,12 @@ Instantiates a new Generator object. **Example** ```js const path = require('path'); -const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example')); +const generator = new Generator('@asyncapi/html-template@3.0.0 --use-new-generator', path.resolve(__dirname, 'example')); ``` **Example** *(Passing custom params to the template)* ```js const path = require('path'); -const generator = new Generator('@asyncapi/html-template', path.resolve(__dirname, 'example'), { +const generator = new Generator('@asyncapi/html-template@3.0.0 --use-new-generator', path.resolve(__dirname, 'example'), { templateParams: { sidebarOrganization: 'byTags' } @@ -487,10 +487,10 @@ Returns the content of a given template file. **Example** ```js const Generator = require('@asyncapi/generator'); -const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html'); +const content = await Generator.getTemplateFile('@asyncapi/html-template@3.0.0 --use-new-generator', 'partials/content.html'); ``` **Example** *(Using a custom `templatesDir`)* ```js const Generator = require('@asyncapi/generator'); -const content = await Generator.getTemplateFile('@asyncapi/html-template', 'partials/content.html', '~/my-templates'); +const content = await Generator.getTemplateFile('@asyncapi/html-template@3.0.0 --use-new-generator', 'partials/content.html', '~/my-templates'); ``` diff --git a/apps/generator/docs/template.md b/apps/generator/docs/template.md index b8f31db01..bddd634b8 100644 --- a/apps/generator/docs/template.md +++ b/apps/generator/docs/template.md @@ -59,7 +59,7 @@ Template Name | Description | Source code `@asyncapi/java-spring-template` | Generates Java Spring service | [Java spring template](https://github.com/asyncapi/java-spring-template) `@asyncapi/java-spring-cloud-stream-template` | Generates Java Spring Cloud Stream service | [Java spring cloud stream template](https://github.com/asyncapi/java-spring-cloud-stream-template) `@asyncapi/python-paho-template` | Generates Python service that uses Paho library | [Python paho template](https://github.com/asyncapi/python-paho-template) -`@asyncapi/html-template` | Generates HTML documentation site | [HTML template](https://github.com/asyncapi/html-template) +`@asyncapi/html-template@3.0.0 --use-new-generator` | Generates HTML documentation site | [HTML template](https://github.com/asyncapi/html-template) `@asyncapi/markdown-template` | Generates documentation in Markdown file | [Markdown template](https://github.com/asyncapi/markdown-template) `@asyncapi/ts-nats-template` | Generates TypeScript NATS client | [TypeScript/Node.js NATS template](https://github.com/asyncapi/ts-nats-template/) `@asyncapi/go-watermill-template` | Generates Go client using Watermill | [GO watermill template](https://github.com/asyncapi/go-watermill-template) diff --git a/apps/generator/docs/usage.md b/apps/generator/docs/usage.md index 344044680..0634a39c5 100644 --- a/apps/generator/docs/usage.md +++ b/apps/generator/docs/usage.md @@ -15,7 +15,7 @@ USAGE 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 + TEMPLATE - Name of the generator template like for example @asyncapi/html-template@3.0.0 --use-new-generator or https://github.com/asyncapi/html-template FLAGS -d, --disable-hook=... Disable a specific hook type or hooks from a given hook type @@ -30,7 +30,7 @@ FLAGS --map-base-url= Maps all schema references from base url to local folder EXAMPLES - $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template --param version=1.0.0 singleFile=true --output ./docs --force-write + $ asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator --param version=1.0.0 singleFile=true --output ./docs --force-write ``` 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: @@ -51,8 +51,8 @@ npm install You can preinstall templates globally before installing the [AsyncAPI CLI](https://www.asyncapi.com/docs/tools/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 +npm install -g @asyncapi/html-template@3.0.0 --use-new-generator@0.16.0 +asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator # The generator uses html-template version 0.16.0 and not the latest version. ``` @@ -60,29 +60,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 +101,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. @@ -122,7 +122,7 @@ asyncapi/cli [COMMAND HERE] docker run --rm -it \ -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,18 +133,18 @@ 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 -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: +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@3.0.0 --use-new-generator` 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')); +const generator = new Generator('@asyncapi/html-template@3.0.0 --use-new-generator', path.resolve(__dirname, 'example')); try { await generator.generateFromURL('https://raw.githubusercontent.com/asyncapi/asyncapi/2.0.0/examples/2.0.0/streetlights.yml'); diff --git a/apps/generator/docs/using-private-template.md b/apps/generator/docs/using-private-template.md index 8d8d9faa9..ce685fee7 100644 --- a/apps/generator/docs/using-private-template.md +++ b/apps/generator/docs/using-private-template.md @@ -26,7 +26,7 @@ npm config set //verdaccio:4873/:_auth=$(echo -n 'username:password' | base64) ## Pulling private template using library: ```javascript -const generator = new Generator('@asyncapi/html-template', 'output', +const generator = new Generator('@asyncapi/html-template@3.0.0 --use-new-generator', 'output', { debug: true, registry: { @@ -38,4 +38,4 @@ const generator = new Generator('@asyncapi/html-template', 'output', } }); ``` -Assuming you host `@asyncapi/html-template` in a private package registry like Verdaccio. To pull this template, you need to provide `registry.url` option that points to the registry URL and `registry.auth` as a base64 encoded value that represents the username and password. Instead of username and password, you can also pass `registry.token`. +Assuming you host `@asyncapi/html-template@3.0.0 --use-new-generator` in a private package registry like Verdaccio. To pull this template, you need to provide `registry.url` option that points to the registry URL and `registry.auth` as a base64 encoded value that represents the username and password. Instead of username and password, you can also pass `registry.token`. diff --git a/apps/generator/docs/versioning.md b/apps/generator/docs/versioning.md index 5409d822b..e957282d8 100644 --- a/apps/generator/docs/versioning.md +++ b/apps/generator/docs/versioning.md @@ -18,14 +18,14 @@ 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 -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 +asyncapi generate fromTemplate asyncapi.yaml @asyncapi/html-template@3.0.0 --use-new-generator@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. \ No newline at end of file