⚙️ Help wanted!

[pastelsky]

Here are a few pieces that we currently need help with

1. Getting a good pre-commit setup, and CI steps
2. Making our styling system saner (currently its a mix of hardcoded values, and CSS vars. Also, the typedoc styles live separate to the next JS App)
3. Dark mode support for docs (Dark mode? #1)
4. Doing a coverage of the top ~200 most used frontend / backend npm packages by type and seeing where tsdocs.dev fails
5. A Command + K search widget for quick search

[alienkarma]

Hi
I would like to help with points 2 and 3.
I can start working on writing a styling system and modularising it.
And then afterward, implementing a dark theme based on the new system.

[pastelsky]

@alienkarma to begin with we'd need to commonize the following into separate variables —

1. Colors
2. Spacing / Sizing
3. Fonts
4. Others

Also note that tsdocs.dev is essentially two separate webapps —
the top webapp is next js powered and has its own styles, whereas the documentation pages are HTML based, generated by typedoc, with a few injected react elements (e.g. header).

We'd ideally need a common system that can be injected in both these webapps for sanity.
Color might be a good one to start with. I like the way open props organises its atomic styles —
https://github.com/argyleink/open-props/tree/main/src

so it would be good to take that as inspiration.

@torchsmith also has a WIP PR for dark mode here —
#13

But I agree that we should get our variables right before patching in more color modes.

Would you mind creating a new issue and discussing the approach there?

[Mahmoudgalalz]

can I got more details about the CI steps, and pre-commit setup?

What to hook to fetch befor the commit, and the CI for what

[difosfor]

First of all, cool! This looks great and I think really solves a problem many of us have and could become a standard moving forwards 👍

I think the main issue we're running into right now is the service frequently breaking down though. At least for me I've been trying to open my package docs every once in a while and it almost never worked with varying errors. Then last week it seemed to work well for one of my packages (@liveryvideo/player) for a while, but not for another (@liveryvideo/interactive-bridge). And then now the whole server seems to be unresponsive again.

I guess there are issues with the server code intermittently hanging or crashing combined with some form of caching?

Could you please keep us posted a bit about these kinds of issues somewhere; perhaps a little service status indicator on the main page and/or a link to articles at blog.tsdocs.dev or so?

In the mean time I'm left wondering what to use for now; I really want to stop having to manually copy paste my docs over to our docsify markdown files, but have not found a practical and reliable solution. I really hope we can get tsdocs working reliably. Could we perhaps also help with that somehow? You didn't list that here. I'll see if we can sponsor you for starters.

[pastelsky]

Yep, I'm aware of the reliability issues affecting the site at the moment.
It is hosted on a small droplet at the moment — but I just pushed out an update that should hopefully make the building more resilient to changes. Prior to this, a single hung build could cause the server to crash.

I have a couple of uptime checks (internal) to keep a watch for a few days to see.

I'm very keen on upping the reliability significantly and getting enough funding to host this on something that can build/serve documentation to more users concurrently @difosfor.

[difosfor]

Great! It's working like a charm now 👍

PS: We're also sponsoring you; keep up the good work!

[mootari]

@pastelsky What kind of support would be the most useful to you to get the site back up and running?

[pastelsky]

@mootari I believe sites like npmx, deno do offer similar docs now (though perhaps not as complete). And agents are pretty good at peeping into API interfaces and type definitions if asked to.

Do you still find value in having a site do this?

[mootari]

@pastelsky I actually came across your project while looking into an issue with deno_doc on npmx and searching for reference docs to compare against. It's not always easy to tell if there's a configuration issue or a bug in the doc generator, and sites like yours do often already handle common mistakes.

But I totally get if you feel it's no longer worth the upkeep and that folks should instead help to improve more widespread solutions.