Typedoc: tsx and highlightjs

[maximkott]

I couldn't figure out how to get tsx code to highlight properly. What am I missing? Highlighjs seems to support tsx out of the box. 🤷🏻‍♂️

[maximkott]

I have an example of generated docs here: https://bytesoftio.github.io/use-value/

I didn‘t give enough details it seems - the tsx does not work inside readme.md

[Gerrit0]

Thanks for the reproduction!

I'm not seeing why this is with a quick look at the code that parses + renders it. The readme is rendered with the {{#markdown}} block, which should call this function: https://github.com/TypeStrong/typedoc/blob/4067f2c838255c4d8cba13bb743172b9f4c2a978/src/lib/output/plugins/MarkedPlugin.ts#L89

I likely won't have time to look at this for at least a month, feel free to take a look and submit a PR if you fix it.

[maximkott]

Thanks for the effort! I will take a look. Maybe hljs is outdated. If you have any other hints on where to look at - let me know please.

[maximkott]

tsx has been added to hljs in 9.14 https://github.com/highlightjs/highlight.js/pull/1663/files#diff-8b1c3fd0d4a6765c16dfd18509182f9d, so thats not the problem.

[maximkott]

They have an open ticket for this: https://github.com/highlightjs/highlight.js/issues/1155
Also here they confirm that tsx is not ready yet (25 days ago at the time of this comment) https://github.com/highlightjs/highlight.js/issues/2484#issuecomment-609966018

[maximkott]

I have a quick fix by using prism.js instead of highlight.js, here is a demo: https://maximkott.github.io/typedoc-default-themes/

This is not a 100% serious PR, more like discovering the alternatives, but if you're interested, I'm glad to help.

[orta]

Coming in late-ish, but I'd recommend https://shiki.matsu.io which we use on the TypeScript website

It uses the same highlighting engine as VS Code and the TS team are the ones maintaining that - so it'll always be up to date and can handle weird cases like generics in JSX etc

[maximkott]

@orta looks very promising, will try that.

[maximkott]

@orta Ive replaced prismjs with shiki. It is a bit hacky because shiki is async and typedoc is full sync. Maybe you guys have a better idea on where to put the workraund.

Shiki demo: https://maximkott.github.io/typedoc-default-themes/

Because of shikis async initial step, prismjs might be more suitable after all?

[Gerrit0]

I'd definitely like to change to the same highlighter that's pretty standard across TS products.
Unfortunately this change will break basically every consumer of the API, so it needs to come with a minor version bump & I can't merge it yet... I'll pull it into the library mode branch though.

Thanks for the PR!

[maximkott]

That‘s what I thought. If you need any further help let me know. In the meantime I‘ve built myself a small wrapper around typedoc with library mode, custom theme and shiki included by default, since I don‘t have to keep it compatible 😅. Hopefully to change back to typedoc as soon as things get merged.

Thank you for the hard work!

[Gerrit0]

Hey @orta, using maximkott's work as a starting point, I'm looking for a way to use shiki to generate HTML with classes instead of inline styles.

Inline styles work if the page is fully static, but break as soon as you want to do anything slightly more complicated like letting users switch between light and dark mode. The new handbook suffers from this. Even in dark mode the code blocks are painful white blocks that don't fit in with the rest of the page... I spent some time looking through the provided API and it doesn't seem to support this. Am I missing something? You mentioned that Shiki uses the same engine as VSCode, and looking at the generated HTML in VSCode, classes are used...

[orta]

This is the technique I'll eventually move to in the TS site: https://fatihkalifa.com/typescript-twoslash#dark/lightmode%20support - lots of discussion here: https://github.com/octref/shiki/issues/33

I believe Shiki does give you the identifier for tokenization like these below, so they could be used as CSS classes instead: