Skip to content

asyncapi-viewer

Render AsyncAPI documents inside your Markdown pages with one element:

<asyncapi-viewer src="asyncapi.yaml"></asyncapi-viewer>

asyncapi-viewer is a Python-Markdown extension, so it works in any tool built on Python-Markdown: MkDocs (with the bundled plugin), Zensical, or plain markdown.markdown(). Rendering happens in the browser through the official AsyncAPI React component, pinned to an exact version and loaded with Subresource Integrity. JSON and YAML both work.

This site is built with the plugin. See the live demo.

Install

pip install asyncapi-viewer

MkDocs quick start

mkdocs.yml
plugins:
  - asyncapi-viewer

Put your AsyncAPI file anywhere under docs/ and reference it from a page. Paths are relative to the Markdown file, or relative to docs/ when they start with /. Absolute http(s):// URLs pass through unchanged.

docs/api/events.md
# Events API

<asyncapi-viewer src="events.yaml" sidebar="false"></asyncapi-viewer>

Or, without raw HTML, as a fenced block whose body uses the same names as the attributes:

docs/api/events.md
```asyncapi
src: events.yaml
sidebar: false
```

A missing document or an invalid attribute is a MkDocs warning, so mkdocs build --strict fails instead of shipping a blank viewer.

What you get

  • One element or one fence, any document. JSON or YAML, AsyncAPI 2.x or 3.x, local file or URL.
  • Rendered in place. The viewer appears where you put the tag, and every tag on a page renders.
  • Pinned and verified assets. The viewer script and stylesheet are loaded from a fixed version with integrity hashes. Self-host them with two config lines. See Configuration.
  • Safe by construction. Nothing from your Markdown is interpolated into JavaScript; per-tag data travels in HTML-escaped attributes.
  • Strict-mode aware. Problems surface as build warnings, not as a blank box in production.

Where next

  • Live demo shows AsyncAPI 2 and 3 documents and several attributes side by side.
  • Attributes is the full reference.
  • Configuration covers plugin options, self-hosting and Content Security Policy.
  • Other tools covers Zensical, plain Python-Markdown and Material's instant navigation.
  • Migration is for users of the older names asyncapi-tag and mkdocs-asyncapi-tag-plugin.

Built and maintained by Weesho Lapara. Found it useful? Buy me a coffee.