Customizing Output

Local plugins

Plugins are the building blocks for extending the TypeDoc output. Plugins export a load function with context of the resolved application.

The following is an example a a basic plugin skeleton:

// @ts-check
 
import { MarkdownApplication } from 'typedoc-plugin-markdown';
 
/**
 * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
 */
export function load(app) {
  // do something with app instance
}

The plugin can then be consumed by adding the path to the plugin in your typedoc.json file:

{
  "plugin": ["typedoc-plugin-markdown", "./local-plugins/my-custom-plugin.mjs"]
}

Note plugins must be consumed as ESM.

See Writing a TypeDoc plugin for more information.

Hooks

Hooks allow strings to be injected into the output in specific locations and are the most basic form of customization.

The following example demonstrates how to use hooks to inject content into the output:

// @ts-check
import { MarkdownHook } from 'typedoc-plugin-markdown';
/**
 * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
 */
export function load(app) {
  app.renderer.markdownHooks.on(
    MarkdownHook.PageEnd,
    () => `**Generated using \`page.end\` hook**`,
  );
}

Hooks can be identified and injected using the following predefined keys:

• "page.begin": Applied at the start of the markdown output.
• "page.end": Applied at the end of the markdown output.
• "content.begin": Applied before the main markdown content is rendered.
• "index.page.begin": Applied at the start of the markdown output on the index page.
• "index.page.end": Applied at the end of the markdown output on the index page.

Page Events

Page events provide a context that can be used to modify the output. The events are emitted before and after the markdown of each page is rendered.

You would typically use this event to modify content of a page.

// @ts-check
import { MarkdownPageEvent } from 'typedoc-plugin-markdown';
/**
 * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
 */
export function load(app) {
  app.renderer.on(MarkdownPageEvent.BEGIN, (page) => {
    page.contents = page.contents.replace('foo', 'bar');
  });
}

The following page events are available:

• MarkdownPageEvent.BEGIN: Applied at the start of the markdown output.
• MarkdownPageEvent.END: Applied at the end of the markdown output.

Async Jobs

Async jobs are used to perform asynchronous tasks before or after rendering with a provided context.

// @ts-check
/**
 * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
 */
export function load(app) {
  app.renderer.preRenderAsyncJobs.push(async (renderer) => {
    await doSomethingAsync(renderer);
  });
 
  app.renderer.postRenderAsyncJobs.push(async (renderer) => {
    await doSomethingAsync(renderer);
  });
}

The following arrays are available:

• preRenderAsyncJobs: A list of async jobs which must be completed before rendering output.
• postRenderAsyncJobs: A list of async jobs which must be completed after rendering output files but before generation is considered successful.