# Plugins

Source: https://api-genie.dev/docs/reference/doc-components/plugins
Part of the reference of [@mykulyak/apigenie-docs](https://api-genie.dev/docs/reference/doc-components.md).
Its other pages: [apg-api-reference and apg-spec](https://api-genie.dev/docs/reference/doc-components/reference-and-spec.md), [OpenAPI elements](https://api-genie.dev/docs/reference/doc-components/openapi.md), [Swagger 2.0 elements](https://api-genie.dev/docs/reference/doc-components/swagger.md), [AsyncAPI elements](https://api-genie.dev/docs/reference/doc-components/asyncapi.md), [Protobuf and gRPC elements](https://api-genie.dev/docs/reference/doc-components/protobuf.md), [GraphQL elements](https://api-genie.dev/docs/reference/doc-components/graphql.md), [Building blocks](https://api-genie.dev/docs/reference/doc-components/building-blocks.md), [Try it out](https://api-genie.dev/docs/reference/doc-components/try-it-out.md), [Keyboard shortcuts](https://api-genie.dev/docs/reference/doc-components/keyboard-shortcuts.md), [Theming](https://api-genie.dev/docs/reference/doc-components/theming.md), [Server-side rendering](https://api-genie.dev/docs/reference/doc-components/server-side-rendering.md), [apigenie-docs build](https://api-genie.dev/docs/reference/doc-components/docs-build.md).

The elements render no `x-` extension of a document on their own. A plugin adds what a site needs:
a renderer for each extension key it knows, views before or after the reference, a hook that
changes Markdown before it is rendered, and hooks that run when the plugin starts and stops. Give
plugins to `<apg-api-reference>` or `<apg-spec>` in their `plugins` property, as a list; the
elements inside use them too. Elements that show the same document (the same `spec-url`, or an
`<apg-spec>` around them) share its plugins: when two of them give a plugin with the same name,
the first one is used.

```js
import { html } from "lit";

const codeSamples = {
	name: "code-samples",
	extensions: {
		"x-codeSamples": ({ value }) => html`${value.map((sample) => html`<h4>${sample.lang}</h4><pre>${sample.source}</pre>`)}`,
	},
};

document.querySelector("apg-api-reference").plugins = [codeSamples];
```

A plugin is your own code: you bundle it or load it with the page like the elements. The elements
never load a plugin from a URL.

## A plugin

| Field | |
| --- | --- |
| `name` | Lowercase letters, digits and dashes, unique among the plugins of a document. |
| `extensions` | A renderer for each key, such as `"x-codeSamples"`. |
| `views` | Views with an `id`, a `title`, a `position` (`start` or `end`, the default), `sidebar` and a `render` function. |
| `markdown(source)` | Returns the Markdown of a description, changed. |
| `init(context)` | Runs when the plugin starts to be used for a document. |
| `configChange(context)` | Runs when an attribute or property of the element that has the plugin changes. |
| `destroy()` | Runs when the plugin is removed from `plugins`, or its element leaves the page. |

The elements refuse a plugin with a bad name, a key that does not start with `x-`, or a field of
the wrong type, and a second plugin with the same name. They report the refused plugin and use the
rest.

The TypeScript types are exported from the package: `DocsPlugin`, `PluginView`,
`ExtensionRenderer`, `ExtensionRenderContext` and `DocsPluginContext`.

## Extension renderers

In an OpenAPI or Swagger 2.0 document, the elements look for `x-` keys on the document's root and
its `info`, on each tag and on each operation. A renderer gets:

| Field | |
| --- | --- |
| `key` | The key, such as `x-codeSamples`. |
| `value` | A copy of the key's value. Changing it does not change the document. |
| `target` | `kind` (`document`, `info`, `tag` or `operation`) and `pointer`, such as `#/paths/~1pets/get`. |
| `auth`, `href`, `navigate` | The same as every hook gets (see below). |

It returns a Lit template, a DOM node (a `DocumentFragment` too), text or nothing (`null`,
`undefined` or Lit's `nothing`). The elements show text as text, never as
HTML, so a value from the document cannot add markup to the page. Each key's output sits below the
description, in a `part="extension"` element whose `data-plugin` and `data-key` attributes name the
plugin and the key. When two plugins render the same key, the first one in `plugins` renders it.

A renderer runs again only when the value, the schemes that have credentials or the language
change. A node it returns stays on the page while the operation updates for other reasons, such as
typing in Try it out, so a widget keeps its state.

## Views

A view shows its `title` as a heading, with what `render(context)` returns below it.

- With `layout="single"`, every view shows before the reference (`position: "start"`) or after it.
- With the sidebar, a view shows at the start or the end of the overview page.
- With `sidebar: true` as well, the view gets an entry at the top or the bottom of the sidebar, and
  a page of its own at `#/plugin/<name>/<id>` (or `<base-path>plugin/<name>/<id>` with
  `routing="history"`).

## The Markdown hook

`markdown(source)` gets the Markdown of a description and returns it changed. The elements render
and sanitize what it returns like the document's own Markdown, so a hook can add Markdown but not
HTML. For anything that needs markup, use an extension renderer or a view.

## What every hook gets

| Field | |
| --- | --- |
| `auth.authorized` | The names of the security schemes that have credentials. |
| `auth.isAuthorized(scheme)` | Whether a scheme has credentials. Plugins never see the credentials themselves. |
| `href(route)` | The URL of a page of the reference, such as `{ kind: "operation", slug: "listPets" }`. |
| `navigate(route)` | Goes to a page, as following a link to it would. |

## When a plugin fails

Each renderer runs in an error boundary. When it throws an error, or returns something the elements
cannot show, the elements show a short message in its place: "The *name* plugin could not show
this." The rest of the page renders as usual. When a Markdown hook fails, the elements render the
Markdown without it. When a lifecycle hook fails, the plugin stays in use.

The elements log every failure to the console with its stack, and fire `apg-plugin-error` once per
failure:

```js
reference.addEventListener("apg-plugin-error", (event) => {
	const { plugin, place, key, view, message } = event.detail;
	reportToMonitoring(plugin, place, key ?? view, message);
});
```

`place` is `plugin` (refused), `extension`, `view`, `markdown`, `init`, `configChange` or
`destroy`.

The boundary catches errors that happen while the elements render. An error a plugin's own node
throws later, from an event handler or a timer, is outside it.

## Server-side rendering

`renderApiReference` renders without plugins. In the browser, the elements add plugin output once
they have hydrated, so the hydrated page first matches the server's. Give a server-rendered
reference its plugins itself: another element that shows the same document and gives plugins as
the page hydrates would add their output before hydration is over.

| Part | |
| --- | --- |
| `extensions` | What plugins render for the `x-` keys of the document, a tag or an operation. |
| `extension` | One key's output. |
| `plugin-error` | The message a failed renderer shows in place of its output. |
| `plugin-view` | A view. |
