How to include custom js?

[hesxenon]

Search terms

include js, include script, custom script source

Question

I'm developing a webcomponent library and I noticed that HTML that is inlined in the documentation is rendered. Would be quite nice to have the webcomponents render but for that I'd have to include the bundled script somehow. Is there a way to do that?

[Gerrit0]

Currently only via a plugin which uses a hook to add it to the page like https://typedoc.org/api/documents/Renderer.Custom_Themes.html#md:hooks

I've been meaning to add a customJs option which behaves like customCss does for a while, just haven't gotten around to it

[Aryakoste]

Hello @Gerrit0 I would like to work on this issue.

[Gerrit0]

Go for it!

[hesxenon]

@Aryakoste thanks for your work on this, but maybe it would be nice to have something like

"customJs": {
  src: "./dist/index.js",
  type: "module"
}

it seems the way this is currently implemented this only allows for non-esm scripts?

@Gerrit0 would you like me to open another issue for this or re-open this issue?

[Gerrit0]

I'm becoming really wary of adding too much behavior via options - TypeDoc already has so many...

This is also really easy to do with a plugin...

import { Application, JSX } from "typedoc";
import fs from "fs";
import path from "path";

/** @param {Application} app */
export function load(app) {
    app.renderer.hooks.on("head.end", (ctx) =>
        JSX.createElement("script", { src: ctx.relativeURL("./assets/custom.js"), type: "module" }),
    );

    app.renderer.on("beginRender", (event) => {
        fs.copyFileSync("path/to/custom.js", path.join(event.outputDirectory, "assets/custom.js"));
    });
}

If we add an option for type, okay... what about defer? async? crossorigin? integrity?

[hesxenon]

absolutely, I get that. I mean I would probably re-use the lib.dom.ts declarations and do something like

customJs: Array<
  Partial<
    PickByValueType<HTMLScriptElement, string | number | boolean>
  > & {src: string}
>

so that consumers can specify any valid script attribute at the cost of being able to specify a string only.

But speaking of plugins: is there a guide to plugin development somewhere? (beside the advice to look at existing plugins)

[Gerrit0]

Unfortunately that API would require a hardcoded special case in the options parser, which is not something I want to add. There are a number of similar options that it'd be convenient to have within objects, but the parser as is doesn't lend itself to it.

[Gerrit0]

For plugin docs, there is the internal-docs folder in this repository and https://typedoc.org/guides/development/