FRESH

Hacker News

We rolled our own documentation site

60 points by nerdypepper

by dont__panic

0 subcomment

I love the linux philosophy at work here. Pandoc is an incredible tool that every documentarian knows. Markdown is a great tool that covers 80%+ of docs requirements (admonitions and tabs are not well-defined in vanilla markdown, for instance, but you don't strictly _need_ those).
I've worked on docs at quite a few companies at this point. Almost every company I've ever seen has built a Rube Goldberg machine and totally overengineered their docs for reasons I simply can't understand. It's funniest when the overengineering doesn't even solve problems better than the vanilla solutions out there like AsciiDoctor and Sphinx. So many useless checks. So much unmaintainable javascript and styling. So many botched search and AI chat implementations. And don't even get me started on Vale, which generally just annoys the hell out of contributors instead of helping them.
Great work on the site, Tangled. Your docs site contains useful instructions and a sidebar that clearly communicates an organization structure. It doesn't peg my CPU or RAM. It's amazing how that makes your site better than 90% of docs sites out there.
One tip: could you add a favicon? Bonus points if it's slightly distinct from your main site's favicon so I can distinguish docs tabs at a glance.

by bryanhogan

1 subcomments

I do have to say that all of the doc tools they mention in the beginning are worse than Astro Starlight[1] and Vitepress[2]. Can highly recommend Astro Starlight for documentation sites, used it for multiple projects myself.
[1]: https://starlight.astro.build/
[2]: https://vitepress.dev/

by gingersnap

8 subcomments

Talking about search on a static docs site, has anyone tried a static pre-generated search like https://lunrjs.com/ ?

by WillAdams

1 subcomments

For folks not familiar with this project:
>Tangled is a decentralized Git hosting and collaboration platform.
it is _not_ about Literate Programming (which is what I was expecting).
A previous active discussion of this project:
https://news.ycombinator.com/item?id=45543899

by butz

0 subcomment

This is great, no javascript. And while I am not a big fan of google search, alternative to open up all docs as single page and use Ctrl+F is neat.

by rileymichael

0 subcomment

> MkDocs: Works great with JS disabled, however the table of contents needs to be maintained via mkdocs.yml, which can be quite tedious.
note that the mkdocs-material folks are now working on https://zensical.org/ which is in rust and _much_ faster. it solves this specific requirement by autogenerating the navigation based on file structure.
it's still early / under active development, but i recently rebuilt our techdocs on top of it. a simple github workflow to aggregate from our two monorepos + some bash-fu to merge them together and voila! no config file headaches

by rvdginste

0 subcomment

I recently created a static site with technical documentation using Antora. Antora uses asciidoc source that it pulls from git repositories. It has a lunr extension for search. It took some time to get familiar with the setup, but I find it very nice to work with. I use it for the documentation of a set of code libraries, and it is a really good fit for that.

by tomovo

0 subcomment

Regarding the "searchability" point: I tried using the Google search field on the left to search for "openbao", which is listed right below as one of the topics. Got 0 results. Second time I tried, I got a reCaptcha from Google itself: a first in years. That's not very reassuring.

by effnorwood

0 subcomment

by gkoberger

2 subcomments

Congrats on the launch!
I run a documentation product, ReadMe. There's a lot of reasons to roll your own, but I'd recommend you also look into a third-party tool like us. One of the biggest reasons to use a product is that the building v1 is easy, but keeping it up to date over time is a lot tougher... you're stuck remembering how to deploy, figuring out a workflow, dealing with multiple versions, etc.
You also just don't get a ton of really great features for your developers... fast typeahead search, AI tools (which your developers increasingly really want), navigation, accessibility and more. ReadMe also lets your developers play around with you API locally and get copy-and-paste code snippets.
(If you're deciding between your own and ReadMe, email me! greg@readme.io; would love to talk)

by sgtwompwomp

1 subcomments

Mintlify is really good. If you're a serious developer tool not sure why you wouldn't use it. For example I went into your docs and I don't see AI chat so I can ask quick, natural language questions. No MCP I can install so Cursor can query. Prob no llms.txt. No quick Copy to Markdown. This stuff is table stakes, if you don't have it and a competitor does, I'm not even considering you guys
It's just a worse developer experience. Fine if you aren't a serious business, but yeah I wouldn't play down the value of Mintlify or similar products. It's seriously good and it's why huge companies use it