[typedoc-plugin-markdown] How to change title format

[Dr-Electron]

trafficstars

Hi, Currently we are using your project to create markdown files which we import in Docusaurus. But the title of the the pages is always Type: TypeName. For example: Class: SomeClass. In Docusaurus that creates the following sidebar structure:

Classes/
├── Class: SomeClass
└── Class: AnotherClass

Would be nice if the title could be customised to only have SomeClass as title.

I'm not sure if any other plugin like the frontmatter one could help here 🤔

[NicolasThierion]

I also wish there was an option to override the Handlebars helpers. At the moment, here is my hacky workaround:

    // override helper to exclude ReflectionKind from sidebar
    Handlebars.registerHelper(
      'reflectionTitle',
      function (shouldEscape = true) {
        const title = [''];
        title.push(
          shouldEscape ? escapeChars(this.model.name) : this.model.name,
        );
        if (this.model.typeParameters) {
          const typeParameters = this.model.typeParameters
            .map((typeParameter) => typeParameter.name)
            .join(', ');
          title.push(`<${typeParameters}${shouldEscape ? '\\>' : '>'}`);
        }
        return title.join('');
      },
    );
    const _registerHelper = Handlebars.registerHelper;
    Handlebars.registerHelper = function (...args): void {
      if (args[0] === 'reflectionTitle') {
        return;
      }

      return _registerHelper.apply(Handlebars, args);
    };

    function escapeChars(str) {
      return str
        .replace(/>/g, '\\>')
        .replace(/_/g, '\\_')
        .replace(/`/g, '\\`')
        .replace(/\|/g, '\\|');
    }

[Dr-Electron]

@tgreyuk cool just tried out next and it works like intended.

But I had to remove the --theme markdown option for it to work. And the docs went from looking like this:

To this:

Why is there a slash after Promise now? And also if I would like to keep the table format, would that be possible?

[tgreyuk]

Hi @Dr-Electron,

Why is there a slash after Promise now?

There shouldn't be. Is this output from Docusaurus?

And also if I would like to keep the table format, would that be possible?

This can be achieved with --parametersFormat table. There is actually a bunch of new options https://www.typedoc-plugin-markdown.org/options .

[Dr-Electron]

There shouldn't be. Is this output from Docusaurus?

We import it in docusaurus but it is not generated by the docusaurus plugin. (We pull the reference docs from outside of docusaurus). Should I create another issue for that problem?

And also if I would like to keep the table format, would that be possible?

This can be achieved with --parametersFormat table. There is actually a bunch of new options https://www.typedoc-plugin-markdown.org/options .

Lovely ❤️ . Really nice changes you made in the next version ❤️

[tgreyuk]

We import it in docusaurus but it is not generated by the docusaurus plugin. (We pull the reference docs from outside of docusaurus).

Ok, I assume you are using Docusaurus 2?. The issue is that the output is now MDX but Docusaurus is not MDX compatible (this is handled by the Docusaurus plugin). This looks to be the same issue as raised here https://github.com/tgreyuk/typedoc-plugin-markdown/issues/564 . I think the best thing here is to offer an opt-out of MDX.

[tgreyuk]

@Dr-Electron in the mean time i've had another idea. You can use the docusaurus-plugin without executing build or start with an exposed cli command generate-typedoc. So you could install docusaurus-plugin-typedoc@next and then run docusaurus generate-typedoc rather than typedoc. This should fix/remove the escaped angle brackets.

[Dr-Electron]

We import it in docusaurus but it is not generated by the docusaurus plugin. (We pull the reference docs from outside of docusaurus).

Ok, I assume you are using Docusaurus 2?. The issue is that the output is now MDX but Docusaurus is not MDX compatible (this is handled by the Docusaurus plugin). This looks to be the same issue as raised here #564 . I think the best thing here is to offer an opt-out of MDX.

Yeah we are still using docusaurus v2. I guess an update to v3 wouldn't help here either? 🤔

[Dr-Electron]

@Dr-Electron in the mean time i've had another idea. You can use the docusaurus-plugin without executing build or start with an exposed cli command generate-typedoc. So you could install docusaurus-plugin-typedoc@next and then run docusaurus generate-typedoc rather than typedoc. This should fix/remove the escaped angle brackets.

The problem with this is, that I need to install docusaurus in that repo too. Only to generate the docs, which are then uploaded and used by the main docusaurus project 😅

[tgreyuk]

Yeah we are still using docusaurus v2. I guess an update to v3 wouldn't help here either?

Upgrading to Docusaurus v3 will fix the issue.

The problem with this is, that I need to install docusaurus in that repo too.

Ok that makes sense. I think there does need to be a workaround for this.

[tgreyuk]

Closing this as original issue fixed.

The mdx issues should be fixed by adding the following to docusuaurus.config:

  markdown: {
    format: 'detect'
  },