Type Info on the Docs & Guides

[flakey5]

Enter your suggestions in details:

Provide type info for code snippets on the docs and guides. For reference, see Hono's docs: https://hono.dev/docs/concepts/middleware.

This is very much so in the backlog until we have less things to do

(slack convo https://openjs-foundation.slack.com/archives/CVAMEJ4UV/p1751225431726929)

[avivkeller]

The program to do this is https://github.com/twoslashes/twoslash

[AugustinMauroy]

The program to do this is https://github.com/twoslashes/twoslash

same author than skiki.

It's will be easy to setup (I think) https://twoslash.netlify.app/guide/highlight

[ovflowd]

[avivkeller]

I've been experimenting with Twoslash today, and there's a slight issue: Twoslash relies on @types/node for type-definitions of a given function. When we publish a new version of Node.js, @types/node is not updated, so the types don't match the version of Node.js we are publishing.

So, while twoslash will work on the guides, it may be difficult to get it set up on the docs.

[ovflowd]

Maybe we can reach out maintainers of two slash? And see if they can support us?

[avivkeller]

Maybe we can reach out maintainers of two slash? And see if they can support us?

I mean, hypothetically, we could use a custom wrapper around twoslash which pulls the data from the documentation that we are generating, but that's a decent amount of boilerplate.

[ovflowd]

I'd rather reach out their maintainer

[avivkeller]

I'd rather reach out their maintainer

And say what? That we need them to perform tedious typing on every Node.js release before it comes out?

I don't think that's a feasible request.

[ovflowd]

No, the suggestion would be for somehow the package to support external references of types. After all the @types/node package is generated pretty much out of our JSON schema (generator)

[avivkeller]

No, the suggestion would be for somehow the package to support external references of types

Ah, ok.

Currently, our documentation generator is configured to allow each document to be generated independently (i.e., the sidebar is built from index.md rather than from a combined set of headers across all files). If we integrate Twoslash using an external reference, would that affect this setup, since (and I may be wrong) it would require loading all the documentation?