Theme customization: Ability to override the comment function

[Jkoutsoumpas]

Search Terms

customization custom theme comment comments custom tags

Problem

I am trying to customize the default theme (0.23.21) with the new plugin system but I can't override/customize/modify the output of tags of the rendered HTML. I can think of the following 4 ways on how to override/extend this:

1. override the comment function of the DefaultThemeRenderContext class by copy-paste'ying its code
2. modify the returned JSX from the comment function of the DefaultThemeRenderContext class
3. manipulate the HTML DOM at runtime using javascript
4. create an entire new Theme from scratch

For the 1st: There is no way with the public API to override the functionality of the comment/tags rendering because the comment method of the DefaultThemeRenderContext uses two internal functions, displayPartsToMarkdown and camelToTitleCase, that are not exported via the public exports of TypeDoc. Of course I can simply copy/paste these functions and use them instead but that will result in a very fragile customization which will need maintenance efforts with every update of TypeDoc in order to keep up with any breaking changes. I would like to avoid this as much as possible.

For the 2nd: It is very cumbersome and against all JSX philosophy/recommendations/best practices (JSX is supposed to be immutable and must stay immutable). It would also have the same issue with updates of TypeDoc.

3rd "solution", is not really a solution because it is not theme customization but complete developing of a new theme. This requires an enormous effort to develop and it would also have the same issue with updates of TypeDoc.

The 4th solution seems more feasible than the rest but it also has problems. It requires big effort and would also have the same issue with updates of TypeDoc.

Suggested Solution

I suggest that TypeDoc officially export the functions (displayPartsToMarkdown and camelToTitleCase) that comment uses in order for the customization to be easier and more robust for in cases of TypeDoc updates.

Or refactor the comment function in order to make it easier to override and customize the rendering of the comments and tags.

Of course, I may am missing something here and there is another way to be able to customize the tags/comment rendering without extensively overriding the TypeDoc internal code that result in fragile customizations.

[Gerrit0]

What exactly are you trying to do? You could set the tag's content property with html/markdown in order to have that rendered... the default theme would still include a header with the tag name, but other than that, it should be possible to add whatever html you need.

I'm not opposed to exporting displayPartsToMarkdown at least (might make it a static method on Comment), camelToTitleCase is an unfortunate thing to export, but probably reasonable as well.

[Jkoutsoumpas]

First of all thanks about the tip for customizing the tag content. However this only allows modifying the content and not the tag name <h3> which I also would like to customize.

What I want to do is this: I want to override the:

<h3>tag_name</h3>
</p>tag_content</p>

with

<div class="myclass">custom_content</div>

In order to completely stylize some tags on how they appear (text and form) and how they function (using javascript to display a js tooltip popup etc, having links for further information etc).

Regardless, modifying the tag content is good enough for my case, therefore please close this if you like.