Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/asyncapi/html-template

HTML template for AsyncAPI Generator. Use it to generate a static docs. It is using AsyncAPI React component under the hood.
https://github.com/asyncapi/html-template

asyncapi generator get- get-global-node-release-workflows get-global-releaserc html nodejs template

Last synced: about 2 months ago
JSON representation

HTML template for AsyncAPI Generator. Use it to generate a static docs. It is using AsyncAPI React component under the hood.

Host: GitHub
URL: https://github.com/asyncapi/html-template
Owner: asyncapi
Created: 2020-03-20T17:12:01.000Z (almost 5 years ago)
Default Branch: master
Last Pushed: 2024-11-29T14:48:09.000Z (about 2 months ago)
Last Synced: 2024-11-30T23:04:41.044Z (about 2 months ago)
Topics: asyncapi, generator, get-, get-global-node-release-workflows, get-global-releaserc, html, nodejs, template
Language: JavaScript
Homepage:
Size: 5.76 MB
Stars: 67
Watchers: 8
Forks: 59
Open Issues: 2
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS

Awesome Lists containing this project

README

        [![AsyncAPI HTML Template](assets/github-repobanner-htmltemp.png)](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.

---

[![All Contributors](https://img.shields.io/badge/all_contributors-17-orange.svg?style=flat-square)](#contributors-)

![npm](https://img.shields.io/npm/dm/@asyncapi/html-template?style=flat-square)

---

- [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/[email protected]

```

> If you use template version v3 with AsyncAPI Generator v2

```bash

asyncapi generate fromTemplate  @asyncapi/[email protected] --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)):

  

    

      
_{James Crowley}
💻 🐛

      
_{Waleed Ashraf}
💻 🐛

      
_{Julian Rabe}
💻

      
_Sebastián
⚠️ 💻

      
_{Gordeev Artem}
💻

      
_{Mitchell Sawatzky}
💻

      
_{Talmiz Ahmed}
💻

    

    

      
_{Jürgen B.}
🚇

      
_{Gabriel Claudino}
💻

      
_{Barbara Szwarc}
📖

      
_{Julian S.}
💻

      
_{Ludovic Dussart}
💻

      
_{David Weber}
💻

      
_{Maciej Urbańczyk}
💻 ⚠️ 🐛 🚧 👀

    

    

      
_{Lukasz Gornicki}
🚧 💻 🐛 👀 ⚠️

      
_{Fran Méndez}
🚧 💻 🐛 👀 ⚠️

      
_{Arya Gupta}
📖

    

  

This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!