How to customise the templates used in docusaurus-plugin-typedoc

[SlicedSilver]

Hi 👋

I would like to customise the templates used within docusaurus-plugin-typedoc. Nothing major, just a few modifications to the handlebar templates (like this file: /packages/typedoc-plugin-markdown/src/resources/templates/reflection.hbs). For example: using a table instead of bullet points in a few places.

What is the best way to achieve this?

I found a similar question here: #189, but I'm unable to get this working and was wondering if:
a) it is still the correct approach?, and
b) if this works with the docusaurus plugin?

Any assistance, or examples, would be greatly appreciated. 🙏

[SlicedSilver]

I've managed to get this working. This may not be the best approach but I'll post what I did in case someone else looks for the answer in the future.

Example of how to override a template and a partial template. In this case, reflection.hbs and member.signature.hbs but this should work for any file within the resources folder of the markdown-theme package for this repo.

1. Creating the override theme

1. Create a folder, named my-typedoc-theme in this example.
2. Create the following folder structure:

• src/
  • resources/
    • partials/
      • member.signature.hbs
    • templates/
      • reflection.hbs
  • index.ts
  • render-utils.ts
  • theme.ts
• tsconfig.json

3. See below for content to put in each of these files.
4. Update docusaurus.config.js to have the following options within the docusaurus-plugin-typedoc:

{
  plugin: ['./my-typedoc-theme/dist'],
  theme: 'my-typedoc-theme',
}

5. Update the package.json as follows:

"scripts": {
  "start": "npm run build-theme-overrides && docusaurus start",
  "build": "npm run build-theme-overrides && docusaurus build",
  "build-theme-overrides": "rm -rf ./typedoc-theme-overrides/dist && tsc -p ./typedoc-theme-overrides/tsconfig.json && cp -R ./typedoc-theme-overrides/src/resources ./typedoc-theme-overrides/dist"
},

Content for files

The content for most of the files is essentially only the parts of the markdown-theme which we need to adjust. You may need to copy across a bit more from those files if you need to make more changes.

tsconfig.json

Essentially a copy of the tsconfig.json included with the markdown-theme

{
  "compilerOptions": {
    "outDir": "./dist",
    "declaration": true,
    "experimentalDecorators": true,
    "lib": ["es2018", "dom"],
    "module": "commonjs",
    "moduleResolution": "node",
    "noImplicitAny": false,
    "noUnusedLocals": false,
    "removeComments": true,
    "sourceMap": false,
    "strictNullChecks": true,
    "target": "es2018"
  },
  "exclude": ["./dist", "./test", "**/*.spec.ts"]
}

index.ts

import { Application } from 'typedoc';

import { MyTypedocTheme } from './theme';

export function load(app: Application) {
  app.renderer.defineTheme('my-typedoc-theme', MyTypedocTheme);
}

render-utils.ts

import * as fs from 'fs';
import * as Handlebars from 'handlebars';
import * as path from 'path';

const TEMPLATE_PATH = path.join(__dirname, 'resources', 'templates');

export const reflectionTemplate = Handlebars.compile(
	fs.readFileSync(path.join(TEMPLATE_PATH, 'reflection.hbs')).toString()
);

export function registerPartials() {
	const partialsFolder = path.join(__dirname, 'resources', 'partials');
	const partialFiles = fs.readdirSync(partialsFolder);
	partialFiles.forEach(partialFile => {
		const partialName = path.basename(partialFile, '.hbs');
		const partialContent = fs
			.readFileSync(partialsFolder + '/' + partialFile)
			.toString();
		Handlebars.registerPartial(partialName, partialContent);
	});
}

theme.ts

import { Renderer } from 'typedoc';
import { MarkdownTheme } from 'typedoc-plugin-markdown';
import {
  ContainerReflection,
  PageEvent
} from 'typedoc';
import {
  reflectionTemplate,
  registerPartials,
} from './render-utils';

export class MyTypedocTheme extends MarkdownTheme {
  constructor(renderer: Renderer) {
    super(renderer);
    registerPartials();
  }

  getReflectionTemplate() {
    return (pageEvent: PageEvent<ContainerReflection>) => {
      return reflectionTemplate(pageEvent, {
        allowProtoMethodsByDefault: true,
        allowProtoPropertiesByDefault: true,
        data: { theme: this },
      });
    };
  }
}

Templates and Partial templates (.hbs files)

Copy a template from the markdown-theme package and make the desired changes.