We rolled our own documentation site
blog.tangled.org19 points by nerdypepper 19 hours ago
19 points by nerdypepper 19 hours ago
Talking about search on a static docs site, has anyone tried a static pre-generated search like https://lunrjs.com/ ?
I use https://pagefind.app/ for search on my website. It’s really easy to add to a static site.
I think https://develop.kde.org/docs/ is using lunrjs for search, but downloading and parsing almost 2MB file of search data creates some hiccups on website during load.
I use Lunr on allaboutberlin.com. It's simple and effective, but searching the whole content would have required loading more files than I was comfortable with. Therefore it only searches titles and descriptions.
There are probably workarounds, but it's the only limitation I can think of. Otherwise Lunr just works.
Basically every Elixir package's docs include search based on Lunr, as it's included by default by ExDoc[1]. It's quite good.
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:
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.
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)
All for the low, low price of $350 US per month!
There's also a free version, and a $79/mo tier. We're also free for open source projects on our higher tiers.
If it's not for you, that's okay! But an increasing number of documentation teams are cross-functional (marketing, sales, engineering, product), and not everyone is comfortable editing content directly in Git and dealing with a release.
Docs are the heart and soul of most devtools, so I think it makes sense a lot of companies want a good product.
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
>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.
It's not the site's job to add those features though. If you want that experience there are ways to get it without adding bloat to every page on the web. Scraping a static site and answering questions/summarizing is a solved problem.
It is the sites job to make documentation available to the users, no?
It’s so odd for a tech focused crowed to be so opposed to newer technology.
Users are getting used to natural language search, not having it will be perceived as friction.
Users are increasingly turning to agentic coding tools, those tools do best when documentation is available via an MCP server. Not having one will make it harder for people to use your product.