import { Application, JSX, ParameterType, RendererEvent } from "typedoc";
/**
* TypeDoc plugin that injects Google Tag Manager (GTM) script into generated documentation.
*
* This plugin adds the GTM container script to the and initializes the data layer
* in all generated HTML pages.
*
* Configuration:
* Add to build.ts ROOT_TYPEDOC_CONFIG:
* ```typescript
* const ROOT_TYPEDOC_CONFIG: TypeDocOptions = {
* ...
* plugin: ["./plugins/gtm"],
* gtmId: "GTM-XXXXXXX",
* };
* ```
*/
declare module "typedoc" {
export interface TypeDocOptionMap {
gtmId: string;
}
}
export function load(app: Application) {
// Register the GTM ID option
app.options.addDeclaration({
name: "gtmId",
help: "Google Tag Manager ID (e.g., GTM-XXXXXXX)",
type: ParameterType.String,
defaultValue: "",
});
// Hook into the renderer begin event to set up the injection hooks
app.renderer.on(RendererEvent.BEGIN, () => {
const gtmId = app.options.getValue("gtmId") as string | undefined;
if (!gtmId) {
app.logger.warn(
"[GTM Plugin] No GTM ID provided. Set 'gtmId' in your TypeDoc configuration."
);
return;
}
// Validate GTM ID format
if (!gtmId.match(/^GTM-[A-Z0-9]+$/)) {
app.logger.error(
`[GTM Plugin] Invalid GTM ID format: "${gtmId}". Expected format: GTM-XXXXXXX`
);
return;
}
app.logger.info(`[GTM Plugin] Injecting GTM ID: ${gtmId}`);
// Hook to inject GTM script into
app.renderer.hooks.on("head.end", () => {
const gtmHeadScript = `
`;
return JSX.createElement(JSX.Raw, { html: gtmHeadScript });
});
// Hook to inject GTM noscript fallback after
app.renderer.hooks.on("body.begin", () => {
const gtmBodyScript = `
`;
return JSX.createElement(JSX.Raw, { html: gtmBodyScript });
});
});
}