[](https://www.asyncapi.com)
HTML template for the [AsyncAPI Generator](https://github.com/asyncapi/generator) using an [AsyncAPI React Component](https://github.com/asyncapi/asyncapi-react) under the hood.
---
[](#contributors-)
---
- [Usage](#usage)
- [Supported parameters](#supported-parameters)
- [Development](#development)
- [Contributors ✨](#contributors-%E2%9C%A8)
## Usage
Install AsyncAPI CLI
```bash
npm install -g @asyncapi/cli
```
Generate using CLI
> If you use template version v1 or v2 with AsyncAPI Generator v1
```bash
asyncapi generate fromTemplate @asyncapi/html-template@2.3.14
```
> If you use template version v3 with AsyncAPI Generator v2
```bash
asyncapi generate fromTemplate @asyncapi/html-template@3.0.0 --use-new-generator
```
You can replace `` with local path or URL pointing to [any AsyncAPI document](https://raw.githubusercontent.com/asyncapi/spec/refs/heads/master/examples/streetlights-kafka-asyncapi.yml).
Look into [Releases](/asyncapi/html-template/releases) of this template to pick up the version you need. It is not recommended to always use the latest in production. Always use a specific version.
## Supported parameters
| Name | Description | Required | Default | Allowed values | Example |
|---|---|---|---|---|---|
| sidebarOrganization | Defines how the sidebar should be organized. Set its value to `byTagsNoRoot` to categorize operations by operations tags. Set its value to `byTags` when you have tags on a root level. These tags are used to model tags navigation and need to have the same tags in operations. | No | undefined | `byTags`, `byTagsNoRoot` | `byTagsNoRoot` |
| baseHref | Sets the base URL for links and forms. | No | `/` | *Any* | `/docs` |
| version | Override the version of your application provided under `info.version` location in the specification file. | No | Version is taken from the spec file. | *Any* ([See Semver versioning](https://semver.org/)) | `1.0.0` |
| singleFile | Set output into one html-file with styles and scripts inside. | No | `false` | `true`,`false` | `true` |
| outFilename | The filename of the output file. | No | `index.html` | *Any* | `asyncapi.html` |
| pdf | Generates output HTML as PDF. | No | `false` | `true`, `false` | `true` |
| pdfTimeout | Timeout (in ms) used to generate the PDF. | No | 30000 | >=0 | 1000 |
| favicon | Defines the URL/Path used for the favicon. | No | `assets/asyncapi-favicon.ico` | Any valid favicon URL/Path. | `"https://studio.asyncapi.com/favicon.ico"` |
| config | Inline stringified JSON or a path to a JSON file to override default React component config. The config override is merged with the default config using the [JSON Merge Patch](https://tools.ietf.org/html/rfc7386) algorithm. | No | `{ "show": { "sidebar": true }, "sidebar": { "showOperations": "byDefault" } }` | [JSON config for the React component](https://github.com/asyncapi/asyncapi-react/blob/master/docs/configuration/config-modification.md#definition) | `{"show":{"sidebar":false}}` |
> **NOTE**: If you only generate an HTML website, set the environment variable `PUPPETEER_SKIP_CHROMIUM_DOWNLOAD` to `true` and the generator will skip downloading chromium.
## Development
The HTML-Template is built with an [AsyncAPI React Component](https://github.com/asyncapi/asyncapi-react). For any changes regarding the styling of the page, rendering of the missing/existing elements, please contribute to the [AsyncAPI React Component](https://github.com/asyncapi/asyncapi-react) repository.
If you want make changes in template itself, please follow:
1. Make sure you have the latest generator installed: `npm install -g @asyncapi/generator`.
1. Modify the template or its helper functions.
>**NOTE:** If you have to modify the [`dummy.yml`](https://github.com/asyncapi/generator/blob/master/test/docs/dummy.yml) file to develop your features, open a PR with the changes in the [asyncapi/generator](https://github.com/asyncapi/generator) repository.
1. Generate output with watcher enabled: `npm run develop`.
>**NOTE:** If your changes are not visible, this is maybe because the `ag` use the already installed `html-template` so you should use the `--install` option
> * run `npm run develop:install`
> * if command failed, delete the cached `html-template` module in your system and re-rerun the command
1. Open HTML in your browser: `open ./test/output/index.html`.
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
