The building blocks of great docs

mux.com

24 pointsleerob3 comments

It's amazing how the web has come full circle now.

2023 web developers: I figured it out y'all. Send HTML from the server.

1994 web developer: ...excuse me? What else would you do?

On my iPhone, when I click on home links (let's say Webhooks & notifications), I'm redirected to the middle of the target page. I'm sure it's a small bug, but it's kind of sad that basic navigation is half broken. On my pet documentation site [1], I've chosen the boring way:

- fully static HTML (Jekyll)

- minimal JavaScript (especially no tracking)

- search is local

I find my site quite reactive without complicated setup and can focus on the doc content. It's also perfect for SEO, "for free"...

[1]: https://hurl.dev

When you hover the links in the sidebar, even when quickly mousing over them, it seems to preload the page text. This makes it download a bunch of data (~120kb/page) and is wasteful. Some kind of timer should fix this as well. Other than that the docs do look quite nice!

Reply on news.ycombinator.com