AsyncAPI for MkDocs

MkDocs plugin for embedding AsyncAPI specs, rendered via the official asyncapi-react web component.

Installation

Install the plugin via pip:
```
pip install mkdocs-asyncapi
```
Add the plugin to your mkdocs.yml:
```
plugins:
  - search
  - asyncapi
```

Configuration

asset_source

Controls where the web component JS/CSS are loaded from. Possible values:

bundled (default): assets vendored into the plugin package, copied into the built site. Works fully offline.
cdn: loads from unpkg.com, pinned to version.

Prefer bundled

Only bundled assets are post-processed (rem → fixed px), which keeps component sizing correct under themes that scale the root font-size (e.g. mkdocs-material). cdn assets skip this step, so their scaling may be off.

plugins:
  - search
  - asyncapi:
      asset_source: cdn

version

The asyncapi-react/web-component version to use for cdn URLs (default: 3.1.4). Has no effect when asset_source is bundled — the vendored assets are always used in that case.

config

Sets the default AsyncAPI React configuration applied to every component on the site. All official config properties are supported (show, expand, sidebar, parserOptions, schemaID, the operation *Label options, extensions, ...).

plugins:
  - search
  - asyncapi:
      config:
        show:
          sidebar: true

Individual components can override the global config (see Options below).

css_import_path

Overrides the stylesheet loaded by every component, instead of the vendored (or CDN) default. Use this when you want a custom-themed stylesheet — e.g. matching your site's brand colors — built from a copy of default.css. The value is used verbatim (unlike src, it is not resolved relative to the current page), so point it at a fully-qualified URL or a site-root-absolute path:

plugins:
  - search
  - asyncapi:
      css_import_path: https://example.com/asyncapi-custom.css

A per-component cssImportPath="..." attribute overrides this for a single component (see Options).

Usage

Use the <asyncapi-component> tag and reference a spec via src:

Local AsyncAPI Spec

<asyncapi-component src="streetlights.yml"/>

src can be either:

a local file included in the docs build, resolved relative to the current page (MkDocs copies it into the site like any other static file)
a remote http(s):// URL, fetched by the browser at view time:

Remote AsyncAPI Spec

<asyncapi-component src="https://raw.githubusercontent.com/asyncapi/spec/master/examples/streetlights-kafka-asyncapi.yml"/>

Options

src (required) — path or URL to the AsyncAPI spec.
config='{...}' — per-component config, deep-merged over the global config (the component's own value wins on conflicts).
schemaFetchOptions='{...}' — optional RequestInit JSON passed to the fetch call for src.
cssImportPath="..." — per-component stylesheet override, wins over the global css_import_path.

Examples

Inline config override

<asyncapi-component src="streetlights.yml" config='{"show":{"info":false}}'/>

See the sample page for these rendered live.