Typedoc: Wrap example tag in codeblock

.gitignore

docs-example-plugin.js

README.md

WrapExampleInCodeBlockPlugin

The plugin automatically wraps the entire text of @example tags in a Markdown typescript code block, so the generated documentation properly renders the code.

I'm using this setup in my comparing library.

docs-example-plugin.ts

import { Application, Context, Converter, ReflectionKind } from 'typedoc';

/**
 * A plugin that wraps the text of `@example` in a Markdown `typescript` code block.
 */
class WrapExampleInCodeBlockPlugin {

  /**
   * Initializes the plugin.
   * @param typedoc The TypeDoc application.
   */
  public initialize(typedoc: Readonly<Application>): void {
    typedoc.converter.on(Converter.EVENT_RESOLVE_BEGIN, (c: Readonly<Context>) => this.onConverterResolveBegin(c));
  }

  /**
   * Triggered when the TypeDoc converter begins resolving a project.
   * @param context Describes the current state the converter is in.
   */
  public onConverterResolveBegin(context: Readonly<Context>): void {
    const project = context.project;
    const reflections = [
      // update if necessary!
      ...project.getReflectionsByKind(ReflectionKind.CallSignature),
      ...project.getReflectionsByKind(ReflectionKind.Class),
      ...project.getReflectionsByKind(ReflectionKind.Interface),
    ];

    for (const reflection of reflections) {
      if (reflection.comment != null && reflection.comment.hasTag('example')) {
        const tag = reflection.comment.getTag('example')!;
        tag.text = '\n```typescript\n' + tag.text.trim() + '\n```\n';
      }
    }
  }
}

/**
 * Initializes the plugin.
 * @param app Reference to the application that is loading the plugin.
 */
export function load(app: Readonly<Application>): void {
  new WrapExampleInCodeBlockPlugin().initialize(app);
}

package.json

{
   "scripts": {
     "predocs": "tsc docs-example-plugin.ts",
     "docs": "typedoc",
   }
}

typedoc.json

{
  "plugin": "./docs-example-plugin.js"
}