Skip to content

Commit

Permalink
Add basic plugin developer docs
Browse files Browse the repository at this point in the history
Closes #521

There's already a fair number of plugin examples which exist, and I don't
ever see taking all of them and merging it into a single document, so this
is probably the best that there will be for plugin development. I
expect that plugin development requires sufficient understanding of
how TypeDoc works that even the best guides won't allow people who haven't
read all of that material to do anything non-trivial anyways...
  • Loading branch information
Gerrit0 committed Dec 28, 2023
1 parent 01be0e1 commit 8eb2261
Showing 1 changed file with 48 additions and 0 deletions.
48 changes: 48 additions & 0 deletions internal-docs/plugins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
# Writing a TypeDoc Plugin

TypeDoc supports plugins which can modify how projects are converted, how converted symbols
are organized, and how they are displayed, among other things. Plugins are Node modules which
export a single `load` function that will be called by TypeDoc with the [Application] instance
which they are to be attached to. Plugins should assume that they may be loaded multiple times
for different applications, and that a single load of an application class may be used to convert
multiple projects.

Plugins may be either ESM or CommonJS.

```js
// @ts-check
import td from "typedoc";
/** @param {td.Application} app */
export function load(app) {
// todo: Add event listeners to app, app.converter, etc.
// this function may be async
}
```

Plugins affect TypeDoc's execution by attaching event listeners to one or many events that will be
fired during conversion and rendering. Events are available on the [Application], [Converter],
[Renderer], and [Serializer]/[Deserializer] classes. There are static `EVENT_*` properties on those
classes which describe the available events.

The best way to learn what's available to plugins is to browse the docs, or look at the source code
for existing plugins. There is a list of currently supported plugins at https://typedoc.org/guides/plugins/

TypeDoc also provides several control hooks for plugins to change it's behavior, they are described
by the [third party symbols](./third-party-symbols.md) and [custom themes](./custom-themes.md) documents.

Plugins which are configurable can add custom options with `app.options.addDeclaration`. [typedoc-plugin-mdn-links]
has an example of the recommended way of doing this.

To figure out what events a plugin should listen to, it is useful to have a high level understanding of how
TypeDoc works. The [development page](https://typedoc.org/guides/development/) on the website describes this.

If you have specific questions regarding plugin development, please open an issue or ask in the
[TypeScript Discord] #typedoc channel.

[Application]: https://typedoc.org/api/classes/Application.html
[Converter]: https://typedoc.org/api/classes/Converter.html
[Renderer]: https://typedoc.org/api/classes/Renderer.html
[Serializer]: https://typedoc.org/api/classes/Serializer.html
[Deserializer]: https://typedoc.org/api/classes/Deserializer.html
[typedoc-plugin-mdn-links]: https://github.com/Gerrit0/typedoc-plugin-mdn-links/blob/main/src/index.ts
[TypeScript Discord]: https://discord.gg/typescript

0 comments on commit 8eb2261

Please sign in to comment.