Export Renderers from public API?

[LekoArts]

Hello!

Thanks for working on the Typedoc 0.28 compatibility 🎉 I'm working on migrating to the latest version and do wonder how to achieve my current logic (in a less hacky way).

I currently have this custom plugin. It feels hacky but it works 😅

In MarkdownRendererEvent.BEGIN I modify the file output locations. You changed output.urls to output.pages which is read-only now. So I can't override it anymore.

/**
 * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
 */
export function load(app) {
  app.renderer.on(MarkdownRendererEvent.BEGIN, output => {
    // Modify the output object
    output.urls = output.urls
      // Do not output README.mdx files
      ?.filter(e => !e.url.endsWith('README.mdx'))
      .map(e => {
        // Convert URLs (by default camelCase) to kebab-case
        const kebabUrl = toKebabCase(e.url);

        e.url = kebabUrl;
        e.model.url = kebabUrl;

        /**
         * For the `@clerk/shared` package it outputs the hooks as for example: shared/react/hooks/use-clerk/functions/use-clerk.mdx.
         * It also places the interfaces as shared/react/hooks/use-organization/interfaces/use-organization-return.mdx
         * Group all those .mdx files under shared/react/hooks
         */
        if (e.url.includes('shared/react/hooks')) {
          e.url = e.url.replace(/\/[^/]+\/(functions|interfaces)\//, '/');
          e.model.url = e.url;
        }

        return e;
      });
  });

  app.renderer.on(MarkdownPageEvent.END, output => {
    const fileName = output.url.split('/').pop();
    const linkReplacements = getRelativeLinkReplacements();

    for (const { pattern, replace } of linkReplacements) {
      if (output.contents) {
        output.contents = output.contents.replace(pattern, replace);
      }
    }

    if (fileName) {
      if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
        if (output.contents) {
          // Remove any headings from the file, irrespective of the level
          output.contents = output.contents.replace(/^#+\s.+/gm, '');
        }
      }
    }
  });
}

My thinking is that I can extend the router defined in https://github.com/typedoc2md/typedoc-plugin-markdown/blob/main/packages/typedoc-plugin-markdown/src/router/routers/member-router.ts to override the buildPages & buildChildPages function to get my desired output (for the first portion of the plugin). I haven't checked https://github.com/TypeStrong/typedoc/blob/master/src/lib/output/router.ts#L125 in total detail yet, but I think my second portion with the linkReplacements can be solved with overriding relativeUrl.

Similar to how I can currently extend the MarkdownTheme and use defineTheme to override parts there.

Anyways, my ask would be: Can you add the routers to the public API or do you not want to? If not, suggestions what I should do instead?

Thanks!

[tgreyuk]

Hello,

You are absolutely on the right lines. Rather than changing the output urls in the event, you should now create a custom router in the method you have described:

custom-router-plugin.mjs

import { MemberRouter } from "typedoc-plugin-markdown";

export function load(app) {
  app.renderer.defineRouter("custom-router", CustomRouter);
}

class CustomRouter extends MemberRouter {
  buildPages(){}
  buildChildPages(){}
  relativeUrl(){}
}

Only thing is as you mention I haven't exported the custom routers publicly so this example will not yet work.

I will move this to the top of the TODO list. I also plan to support all the TypeDoc default core routers (which only require small tweak to get working).

[LekoArts]

Ok, great, that's good to know! The upgrade to 0.28 isn't blocking me in any way so feel free to take your time on doing this, I don't want to rush you.

Will wait for the export of those classes then 😊

[tgreyuk]

Routers exposed in [email protected].

Here is a pointless example:

import { ReflectionKind } from 'typedoc';
import { MemberRouter } from 'typedoc-plugin-markdown';


export function load(app) {
  app.renderer.defineRouter('custom-router', CustomRouter);
}

export class CustomRouter extends MemberRouter {

  getIdealBaseName(reflection) {
    if (reflection.kind === ReflectionKind.Class) {
      return `custom-class-directory/${reflection.name}`;
    }
    return super.getIdealBaseName(reflection);
  }


  relativeUrl(from, to) {
    return `wiki/${super.relativeUrl(from, to)}`;
  }
}

[LekoArts]

Thanks a lot!

[LekoArts]

@tgreyuk Hey 👋 I'm wanting to override shouldWritePage without TS complaining at me.

Any reason why all methods inside MemberRouter are marked as private as opposed to public or protected?

[tgreyuk]

Hello :)

I suppose it is to be defensive and if possible only expose methods available on the TypeDoc BaseRouter abstract class. There is quite a bit of code in there that id like to strip out as its is mainly to make stuff backward compatible and I am not sure if that method will exist in future iterations.

[LekoArts]

Ok, yeah, that's fine 👍 As you already saw below I got things working how I wanted without it

[LekoArts]

This is so much nicer with the router class 👍

// @ts-check
import { MemberRouter } from "typedoc-plugin-markdown"

/**
 * @param {string} str
 */
function toKebabCase(str) {
  return str.replace(/((?<=[a-z\d])[A-Z]|(?<=[A-Z\d])[A-Z](?=[a-z]))/g, '-$1').toLowerCase();
}

/**
 * @param {import('typedoc-plugin-markdown').MarkdownApplication} app
 */
export function load(app) {
  app.renderer.defineRouter('clerk-router', ClerkRouter)
}

/**
 * Our custom router that changes the file output
 * @extends MemberRouter
 */
class ClerkRouter extends MemberRouter {
  /**
   * @param {import('typedoc').ProjectReflection} project 
   */
  buildPages(project) {
    const pages = super.buildPages(project)

    const modifiedPages = pages
      // Do not output README files
      .filter(page => !page.url.toLocaleLowerCase().endsWith('readme.mdx'))

    return modifiedPages
  }

  /**
   * @param {import('typedoc').Reflection} reflection 
   */
  getIdealBaseName(reflection) {
    const original = super.getIdealBaseName(reflection)
    // Convert URLs (by default camelCase) to kebab-case
    const kebabCase = toKebabCase(original)

    return kebabCase
  }
}

[tgreyuk]

Yes I think it is a great improvement. Thanks for trying things out and providing feedback - very useful!!