asyncapi-tag 1.0.0__tar.gz

asyncapi_tag-1.0.0/LICENSE

@@ -0,0 +1,6 @@
+MIT License
+
+Copyright [2024] [Weesho Lapara]
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

asyncapi_tag-1.0.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: asyncapi-tag
+Version: 1.0.0
+Summary: Render AsyncAPI documents in Markdown with an <asyncapi-tag> element. Python-Markdown extension with a MkDocs plugin.
+Author-email: Weesho Lapara <support@weesholapara.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Weesho-Lapara/asyncapi-tag
+Project-URL: Changelog, https://github.com/Weesho-Lapara/asyncapi-tag/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Weesho-Lapara/asyncapi-tag/issues
+Keywords: asyncapi,markdown,mkdocs,documentation,event-driven,api
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Framework :: MkDocs
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Markdown>=3.4
+Provides-Extra: mkdocs
+Requires-Dist: mkdocs>=1.5; extra == "mkdocs"
+Provides-Extra: test
+Requires-Dist: mkdocs>=1.5; extra == "test"
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# asyncapi-tag
+
+Render [AsyncAPI](https://www.asyncapi.com/) documents inside Markdown pages with a single element:
+
+```html
+<asyncapi-tag src="asyncapi.yaml"></asyncapi-tag>
+```
+
+`asyncapi-tag` is a [Python-Markdown](https://python-markdown.github.io/) extension, so it works in
+any tool built on Python-Markdown. It ships with a plugin for [MkDocs](https://www.mkdocs.org/)
+that resolves document paths the same way MkDocs resolves links. Rendering in the browser is done
+by the official [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react), pinned to
+an exact version and loaded with Subresource Integrity. JSON and YAML documents both work.
+
+> Formerly published as `mkdocs-asyncapi-tag-plugin`. See [Migrating](#migrating-from-mkdocs-asyncapi-tag-plugin).
+
+## MkDocs
+
+```sh
+pip install asyncapi-tag
+```
+
+```yaml
+# mkdocs.yml
+plugins:
+  - asyncapi-tag
+```
+
+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 are
+passed through unchanged.
+
+```markdown
+<!-- docs/api/events.md -->
+# Events API
+
+<asyncapi-tag src="events.yaml" sidebar="false"></asyncapi-tag>
+```
+
+A missing document or an invalid attribute is reported as a MkDocs warning, so `mkdocs build
+--strict` fails instead of shipping a broken page.
+
+### Plugin options
+
+```yaml
+plugins:
+  - asyncapi-tag:
+      load_assets: true              # emit the viewer script and stylesheet (default: true)
+      viewer_js: https://unpkg.com/@asyncapi/react-component@3.2.1/browser/standalone/index.js
+      viewer_js_integrity: sha384-…  # set to '' to omit the integrity attribute
+      viewer_css: https://unpkg.com/@asyncapi/react-component@3.2.1/styles/default.min.css
+      viewer_css_integrity: sha384-…
+```
+
+To self-host the viewer, copy the two files into `docs/` and point the options at them.
+Relative paths are resolved per page like `src` is:
+
+```yaml
+plugins:
+  - asyncapi-tag:
+      viewer_js: assets/asyncapi/index.js
+      viewer_js_integrity: ''
+      viewer_css: assets/asyncapi/default.min.css
+      viewer_css_integrity: ''
+```
+
+Or set `load_assets: false` and load the files yourself through `extra_javascript` and
+`extra_css`. The page-side runner script is still needed in that case; copy it from
+`asyncapi_tag.assets.RUNNER_JS`.
+
+## Plain Python-Markdown
+
+```python
+import markdown
+
+html = markdown.markdown(text, extensions=["asyncapi_tag"])
+```
+
+Extension options (pass them as `extension_configs={"asyncapi_tag": {...}}`):
+
+| Option | Default | Description |
+|---|---|---|
+| `viewer_js`, `viewer_css` | pinned unpkg URLs | Where to load the viewer from |
+| `viewer_js_integrity`, `viewer_css_integrity` | matching SRI hashes | Empty string omits the attribute |
+| `load_assets` | `True` | Emit the loader with the first tag on a page |
+| `url_resolver` | identity | Callable mapping `src` (and relative asset URLs) to what the browser fetches |
+| `warn` | `logging` | Callable receiving warning messages |
+
+## Attributes
+
+Only `src` is required. Attribute names are case-insensitive. Boolean attributes accept
+`true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`; a bare attribute means `true`.
+
+| Attribute | Values | Default | Effect |
+|---|---|---|---|
+| `src` | path or URL | required | The AsyncAPI document (JSON or YAML) |
+| `id` | string | `asyncapi-tag-N` | HTML id of the container element |
+| `sidebar` | boolean | `true` | Show the navigation sidebar |
+| `info` | boolean | `true` | Show the info section |
+| `servers` | boolean | `true` | Show servers |
+| `operations` | boolean | `true` | Show operations |
+| `messages` | boolean | `true` | Show messages |
+| `schemas` | boolean | `true` | Show schemas |
+| `errors` | boolean | `true` | Show parser errors |
+| `showMessageExamples` | boolean | viewer default | Show examples for standalone messages |
+| `messageExamples` | boolean | `true` | Expand message examples |
+| `showServers` | `byDefault`, `bySpecTags`, `byServersTags` | `byDefault` | How the sidebar groups servers |
+| `showOperations` | `byDefault`, `bySpecTags`, `byOperationsTags` | `byDefault` | How the sidebar groups operations |
+| `useChannelAddressAsIdentifier` | boolean | viewer default | AsyncAPI v3: label operations by channel address |
+| `publishLabel`, `subscribeLabel` | string | `PUB`, `SUB` | Operation labels for AsyncAPI v2 |
+| `sendLabel`, `receiveLabel`, `requestLabel`, `replyLabel` | string | `SEND`, `RECEIVE`, `REQUEST`, `REPLY` | Operation labels for AsyncAPI v3 |
+| `parserOptions` | JSON object | viewer default | Passed to the AsyncAPI parser, e.g. `parserOptions='{"applyTraits": false}'` |
+| `schemaID` | string | container id | The viewer's `schemaID` option |
+
+These map onto the React component's
+[configuration](https://github.com/asyncapi/asyncapi-react/blob/master/docs/configuration/config-modification.md).
+Defaults for `sidebar` and `messageExamples` follow earlier releases of this plugin rather than the
+viewer, so existing pages keep their look.
+
+## How it works
+
+Each tag becomes a `<div class="asyncapi-tag">` carrying the document URL and the viewer
+configuration as HTML-escaped data attributes. The first tag on a page also emits the viewer's
+stylesheet and script and a short runner script. The runner fetches each document as text, hands it
+to `AsyncApiStandalone.render`, and prints a visible error inside the container if fetching or
+rendering fails. No content from the Markdown source is interpolated into JavaScript.
+
+Tags inside fenced or indented code blocks are left alone, so you can document the syntax.
+
+Material for MkDocs users with `navigation.instant` enabled are covered: the runner re-scans the
+page on Material's `document$` event.
+
+## Migrating from mkdocs-asyncapi-tag-plugin
+
+1. Replace `mkdocs-asyncapi-tag-plugin` with `asyncapi-tag` in your requirements. The plugin id in
+   `mkdocs.yml` is unchanged (`asyncapi-tag`).
+2. Remove the `asyncapi_file` plugin option. MkDocs already copies every non-Markdown file under
+   `docs/` into the site; the option now only prints a deprecation warning.
+3. Use a path relative to the page (or `/`-prefixed relative to `docs/`) in `src`. Earlier versions
+   emitted the build machine's filesystem path, so only `/`-prefixed paths ever worked; those still work.
+4. String attributes such as `publishLabel="PUBLISH"` and `showServers="bySpecTags"` now take
+   effect. Earlier versions silently discarded them.
+
+`mkdocs-asyncapi-tag-plugin` 1.0.0 is a deprecated shim that only depends on this package, so
+upgrading it also works, but no further releases will be made under the old name.
+
+## Updating the pinned viewer
+
+```sh
+python scripts/update_viewer.py          # latest @asyncapi/react-component
+python scripts/update_viewer.py 3.2.1    # specific version
+```
+
+The script rewrites the version, URLs and SRI hashes in `src/asyncapi_tag/assets.py`.
+
+## Development
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+The JavaScript runner is syntax-checked with `node` when it is installed. See `AGENTS.md` for the
+repository layout and release procedure.
+
+## License
+
+MIT

asyncapi_tag-1.0.0/README.md

@@ -0,0 +1,169 @@
+# asyncapi-tag
+
+Render [AsyncAPI](https://www.asyncapi.com/) documents inside Markdown pages with a single element:
+
+```html
+<asyncapi-tag src="asyncapi.yaml"></asyncapi-tag>
+```
+
+`asyncapi-tag` is a [Python-Markdown](https://python-markdown.github.io/) extension, so it works in
+any tool built on Python-Markdown. It ships with a plugin for [MkDocs](https://www.mkdocs.org/)
+that resolves document paths the same way MkDocs resolves links. Rendering in the browser is done
+by the official [AsyncAPI React component](https://github.com/asyncapi/asyncapi-react), pinned to
+an exact version and loaded with Subresource Integrity. JSON and YAML documents both work.
+
+> Formerly published as `mkdocs-asyncapi-tag-plugin`. See [Migrating](#migrating-from-mkdocs-asyncapi-tag-plugin).
+
+## MkDocs
+
+```sh
+pip install asyncapi-tag
+```
+
+```yaml
+# mkdocs.yml
+plugins:
+  - asyncapi-tag
+```
+
+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 are
+passed through unchanged.
+
+```markdown
+<!-- docs/api/events.md -->
+# Events API
+
+<asyncapi-tag src="events.yaml" sidebar="false"></asyncapi-tag>
+```
+
+A missing document or an invalid attribute is reported as a MkDocs warning, so `mkdocs build
+--strict` fails instead of shipping a broken page.
+
+### Plugin options
+
+```yaml
+plugins:
+  - asyncapi-tag:
+      load_assets: true              # emit the viewer script and stylesheet (default: true)
+      viewer_js: https://unpkg.com/@asyncapi/react-component@3.2.1/browser/standalone/index.js
+      viewer_js_integrity: sha384-…  # set to '' to omit the integrity attribute
+      viewer_css: https://unpkg.com/@asyncapi/react-component@3.2.1/styles/default.min.css
+      viewer_css_integrity: sha384-…
+```
+
+To self-host the viewer, copy the two files into `docs/` and point the options at them.
+Relative paths are resolved per page like `src` is:
+
+```yaml
+plugins:
+  - asyncapi-tag:
+      viewer_js: assets/asyncapi/index.js
+      viewer_js_integrity: ''
+      viewer_css: assets/asyncapi/default.min.css
+      viewer_css_integrity: ''
+```
+
+Or set `load_assets: false` and load the files yourself through `extra_javascript` and
+`extra_css`. The page-side runner script is still needed in that case; copy it from
+`asyncapi_tag.assets.RUNNER_JS`.
+
+## Plain Python-Markdown
+
+```python
+import markdown
+
+html = markdown.markdown(text, extensions=["asyncapi_tag"])
+```
+
+Extension options (pass them as `extension_configs={"asyncapi_tag": {...}}`):
+
+| Option | Default | Description |
+|---|---|---|
+| `viewer_js`, `viewer_css` | pinned unpkg URLs | Where to load the viewer from |
+| `viewer_js_integrity`, `viewer_css_integrity` | matching SRI hashes | Empty string omits the attribute |
+| `load_assets` | `True` | Emit the loader with the first tag on a page |
+| `url_resolver` | identity | Callable mapping `src` (and relative asset URLs) to what the browser fetches |
+| `warn` | `logging` | Callable receiving warning messages |
+
+## Attributes
+
+Only `src` is required. Attribute names are case-insensitive. Boolean attributes accept
+`true`/`false`, `1`/`0`, `yes`/`no`, `on`/`off`; a bare attribute means `true`.
+
+| Attribute | Values | Default | Effect |
+|---|---|---|---|
+| `src` | path or URL | required | The AsyncAPI document (JSON or YAML) |
+| `id` | string | `asyncapi-tag-N` | HTML id of the container element |
+| `sidebar` | boolean | `true` | Show the navigation sidebar |
+| `info` | boolean | `true` | Show the info section |
+| `servers` | boolean | `true` | Show servers |
+| `operations` | boolean | `true` | Show operations |
+| `messages` | boolean | `true` | Show messages |
+| `schemas` | boolean | `true` | Show schemas |
+| `errors` | boolean | `true` | Show parser errors |
+| `showMessageExamples` | boolean | viewer default | Show examples for standalone messages |
+| `messageExamples` | boolean | `true` | Expand message examples |
+| `showServers` | `byDefault`, `bySpecTags`, `byServersTags` | `byDefault` | How the sidebar groups servers |
+| `showOperations` | `byDefault`, `bySpecTags`, `byOperationsTags` | `byDefault` | How the sidebar groups operations |
+| `useChannelAddressAsIdentifier` | boolean | viewer default | AsyncAPI v3: label operations by channel address |
+| `publishLabel`, `subscribeLabel` | string | `PUB`, `SUB` | Operation labels for AsyncAPI v2 |
+| `sendLabel`, `receiveLabel`, `requestLabel`, `replyLabel` | string | `SEND`, `RECEIVE`, `REQUEST`, `REPLY` | Operation labels for AsyncAPI v3 |
+| `parserOptions` | JSON object | viewer default | Passed to the AsyncAPI parser, e.g. `parserOptions='{"applyTraits": false}'` |
+| `schemaID` | string | container id | The viewer's `schemaID` option |
+
+These map onto the React component's
+[configuration](https://github.com/asyncapi/asyncapi-react/blob/master/docs/configuration/config-modification.md).
+Defaults for `sidebar` and `messageExamples` follow earlier releases of this plugin rather than the
+viewer, so existing pages keep their look.
+
+## How it works
+
+Each tag becomes a `<div class="asyncapi-tag">` carrying the document URL and the viewer
+configuration as HTML-escaped data attributes. The first tag on a page also emits the viewer's
+stylesheet and script and a short runner script. The runner fetches each document as text, hands it
+to `AsyncApiStandalone.render`, and prints a visible error inside the container if fetching or
+rendering fails. No content from the Markdown source is interpolated into JavaScript.
+
+Tags inside fenced or indented code blocks are left alone, so you can document the syntax.
+
+Material for MkDocs users with `navigation.instant` enabled are covered: the runner re-scans the
+page on Material's `document$` event.
+
+## Migrating from mkdocs-asyncapi-tag-plugin
+
+1. Replace `mkdocs-asyncapi-tag-plugin` with `asyncapi-tag` in your requirements. The plugin id in
+   `mkdocs.yml` is unchanged (`asyncapi-tag`).
+2. Remove the `asyncapi_file` plugin option. MkDocs already copies every non-Markdown file under
+   `docs/` into the site; the option now only prints a deprecation warning.
+3. Use a path relative to the page (or `/`-prefixed relative to `docs/`) in `src`. Earlier versions
+   emitted the build machine's filesystem path, so only `/`-prefixed paths ever worked; those still work.
+4. String attributes such as `publishLabel="PUBLISH"` and `showServers="bySpecTags"` now take
+   effect. Earlier versions silently discarded them.
+
+`mkdocs-asyncapi-tag-plugin` 1.0.0 is a deprecated shim that only depends on this package, so
+upgrading it also works, but no further releases will be made under the old name.
+
+## Updating the pinned viewer
+
+```sh
+python scripts/update_viewer.py          # latest @asyncapi/react-component
+python scripts/update_viewer.py 3.2.1    # specific version
+```
+
+The script rewrites the version, URLs and SRI hashes in `src/asyncapi_tag/assets.py`.
+
+## Development
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+The JavaScript runner is syntax-checked with `node` when it is installed. See `AGENTS.md` for the
+repository layout and release procedure.
+
+## License
+
+MIT

asyncapi_tag-1.0.0/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "asyncapi-tag"
+dynamic = ["version"]
+description = "Render AsyncAPI documents in Markdown with an <asyncapi-tag> element. Python-Markdown extension with a MkDocs plugin."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Weesho Lapara", email = "support@weesholapara.com" }]
+keywords = ["asyncapi", "markdown", "mkdocs", "documentation", "event-driven", "api"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Web Environment",
+    "Framework :: MkDocs",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Documentation",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Text Processing :: Markup :: Markdown",
+]
+dependencies = ["Markdown>=3.4"]
+
+[project.optional-dependencies]
+mkdocs = ["mkdocs>=1.5"]
+test = ["mkdocs>=1.5", "pytest>=7"]
+
+[project.urls]
+Homepage = "https://github.com/Weesho-Lapara/asyncapi-tag"
+Changelog = "https://github.com/Weesho-Lapara/asyncapi-tag/blob/main/CHANGELOG.md"
+Issues = "https://github.com/Weesho-Lapara/asyncapi-tag/issues"
+
+[project.entry-points."markdown.extensions"]
+asyncapi_tag = "asyncapi_tag.extension:AsyncAPITagExtension"
+
+[project.entry-points."mkdocs.plugins"]
+asyncapi-tag = "asyncapi_tag.mkdocs_plugin:AsyncAPIPlugin"
+
+[tool.setuptools.dynamic]
+version = { attr = "asyncapi_tag.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

asyncapi_tag-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

asyncapi_tag-1.0.0/src/asyncapi_tag/__init__.py

@@ -0,0 +1,28 @@
+"""Render AsyncAPI documents in Markdown with an ``<asyncapi-tag>`` element.
+
+The package is a `Python-Markdown <https://python-markdown.github.io/>`_
+extension (:class:`asyncapi_tag.extension.AsyncAPITagExtension`) and a thin
+MkDocs plugin around it (:class:`asyncapi_tag.mkdocs_plugin.AsyncAPIPlugin`).
+"""
+
+from asyncapi_tag.assets import (
+    VIEWER_CSS_INTEGRITY,
+    VIEWER_CSS_URL,
+    VIEWER_JS_INTEGRITY,
+    VIEWER_JS_URL,
+    VIEWER_VERSION,
+)
+from asyncapi_tag.extension import AsyncAPITagExtension, makeExtension
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "AsyncAPITagExtension",
+    "makeExtension",
+    "VIEWER_VERSION",
+    "VIEWER_JS_URL",
+    "VIEWER_JS_INTEGRITY",
+    "VIEWER_CSS_URL",
+    "VIEWER_CSS_INTEGRITY",
+    "__version__",
+]

asyncapi_tag-1.0.0/src/asyncapi_tag/assets.py

@@ -0,0 +1,106 @@
+"""Pinned viewer assets and the browser-side loader.
+
+The viewer is the standalone bundle of ``@asyncapi/react-component``. The
+version, URLs and Subresource Integrity hashes below are updated together
+with ``scripts/update_viewer.py``; do not edit them by hand.
+"""
+
+from __future__ import annotations
+
+import html
+
+# --- managed by scripts/update_viewer.py ------------------------------------
+VIEWER_VERSION = "3.2.1"
+VIEWER_JS_URL = "https://unpkg.com/@asyncapi/react-component@3.2.1/browser/standalone/index.js"
+VIEWER_JS_INTEGRITY = "sha384-wy5bSOazlkSKMGH7XMW6+pK8ho8+rCPr7mTqKdAb/dvfwXAPWCFivgr3C7wJMFAh"
+VIEWER_CSS_URL = "https://unpkg.com/@asyncapi/react-component@3.2.1/styles/default.min.css"
+VIEWER_CSS_INTEGRITY = "sha384-oo9RoQcacP++XdMX6CjTucTvASEORHX3chFik0/V2kHcsHiVboGyWZztGeq/0bum"
+# ---------------------------------------------------------------------------
+
+CONTAINER_CLASS = "asyncapi-tag"
+
+# Runs once per page. It finds every container the extension emitted, fetches
+# the AsyncAPI document as text (JSON or YAML, the viewer parses both) and
+# renders it. Nothing from the Markdown source is interpolated into this
+# script: per-tag data travels in HTML data attributes, which are HTML-escaped.
+RUNNER_JS = """\
+(function () {
+  "use strict";
+  var SELECTOR = ".asyncapi-tag[data-asyncapi-src]";
+  function showError(el, message) {
+    el.textContent = "";
+    var p = document.createElement("p");
+    p.className = "asyncapi-tag-error";
+    p.textContent = "AsyncAPI viewer: " + message;
+    el.appendChild(p);
+  }
+  function render(el) {
+    if (el.getAttribute("data-asyncapi-state")) { return; }
+    el.setAttribute("data-asyncapi-state", "loading");
+    var src = el.getAttribute("data-asyncapi-src");
+    var config = {};
+    try {
+      config = JSON.parse(el.getAttribute("data-asyncapi-config") || "{}");
+    } catch (err) {
+      showError(el, "invalid configuration (" + err.message + ")");
+      return;
+    }
+    if (!window.AsyncApiStandalone) {
+      showError(el, "the viewer script did not load; check the browser console and any Content Security Policy.");
+      return;
+    }
+    fetch(src, { credentials: "same-origin" }).then(function (response) {
+      if (!response.ok) {
+        throw new Error("could not fetch " + src + " (HTTP " + response.status + ")");
+      }
+      return response.text();
+    }).then(function (text) {
+      return window.AsyncApiStandalone.render({ schema: text, config: config }, el);
+    }).then(function () {
+      el.setAttribute("data-asyncapi-state", "rendered");
+    }).catch(function (err) {
+      showError(el, err && err.message ? err.message : String(err));
+      if (window.console) { console.error("asyncapi-tag:", err); }
+    });
+  }
+  function renderAll() {
+    var nodes = document.querySelectorAll(SELECTOR);
+    for (var i = 0; i < nodes.length; i++) { render(nodes[i]); }
+  }
+  renderAll();
+  /* Material for MkDocs instant navigation swaps page content without a reload. */
+  if (window.document$ && typeof window.document$.subscribe === "function") {
+    window.document$.subscribe(renderAll);
+  }
+})();
+"""
+
+
+def _attr(name: str, value: str) -> str:
+    return f' {name}="{html.escape(value, quote=True)}"'
+
+
+def loader_html(
+    js_url: str,
+    css_url: str,
+    js_integrity: str = "",
+    css_integrity: str = "",
+) -> str:
+    """Return the HTML that loads the viewer and runs it on the page.
+
+    Integrity attributes are emitted only when a hash is given, so the loader
+    also works for self-hosted copies of the viewer.
+    """
+    parts = []
+    if css_url:
+        attrs = _attr("rel", "stylesheet") + _attr("href", css_url)
+        if css_integrity:
+            attrs += _attr("integrity", css_integrity) + _attr("crossorigin", "anonymous")
+        parts.append(f"<link{attrs}>")
+    if js_url:
+        attrs = _attr("src", js_url)
+        if js_integrity:
+            attrs += _attr("integrity", js_integrity) + _attr("crossorigin", "anonymous")
+        parts.append(f"<script{attrs}></script>")
+    parts.append(f"<script>{RUNNER_JS}</script>")
+    return "\n".join(parts)