we rolled our own documentation site
86 points by op
86 points by op
I use pagefind for search on my site. It’s really easy to add to a static website.
I use it at work on a site hosted as github (self hosted enterprise deployment) pages. Works great indeed.
Very cool. I decided to go with a sitemap for my static docs: https://pico.sh/sitemap
I feel like it’s mostly close enough but to be fair our scope is much smaller
I use it on my site too, currently. IMHO, its experience is worse than Algolia, which I used to use, but it is a client-side only library that doesn't require a cloud server provider or self-hosting anything, so I'd consider it a win.
https://ui.pagefind.app/ is in beta, if you want to jump to a better experience early :)
( and if that doesn't cut the mustard I would love to find out what else pagefind could improve on! )
Cool. Was not on my radar. Requires JS? It seems like docs.tangled.org has a requirement not to use JS anywhere
They are implicitly relying on JavaScript by redirecting search to Google 😜 I also prefer to avoid JavaScript, but I use it on my search page because pagefind is MUCH better than Google for site-specific search, and elsewhere on my site JS is great for fun graphical toys.
I was going to say you have to either have code on the server or the client, but you could just generate an index page when building a static site and let people Ctrl+F. I might have to give that a shot sometime!
Congrats on the new site.
Lives in our monorepo
Fabrizio Benedetti coined a good term for this approach: sidecar. In that post Fabrizio is neutral re: what the best approach to docs-as-code is, but I have strong opinions that sidecar is the best and should be the default. The closer docs are to the relevant code, the more likely maintainers are to keep the docs up-to-date. Having docs alongside code opens up a lot of useful automation, too.
There is no native search on the site for now
In-site search (ISS) is really important. I caution against treating this as a nice-to-have. I always instrument my sites to track how much ISS is used, and I'm always surprised at how popular it is. The other main benefit of providing ISS is that the search queries provide really valuable insight re: what kinds of information your users are looking for (assuming that you're logging the queries somewhere e.g. Google Analytics).
The main drawback of deferring to Google Search is that Search can be quite slow to update its index of small, less-trafficked sites.
evaluating the ecosystem
Sphinx is my goto. Great extension system with a very large ecosystem, fairly easy to spin up your own theme, decent client-side search (requires JS though), supports Markdown if you hate reStructuredText (but rST has a lot of advantages over MD IMO), decent docs, actively maintained for +15 years now
Agreed about Sphinx. I've never tried using it for non-Python-based tools or libraries. However, for Python-based tools and libraries, cross-references seem strictly more annoyance or work. rST really is fine once you write or read a few pages worth of it.
I've never tried to use it this way, but it seems especially promising for libraries with multiple language frontends. You should be able to simply reference one language's bindings from another!
I first combined all our individual markdown files into one big DOCS.md file.
How do you specify the order of the files when combining them? It seems this was done manually. If you automate that for consistent repetition, then you have to write down the list of files somewhere and then it is effectively the same as MkDocs and MdBook.
Alternatively, they plan to maintain their documentation as a single big md file. That doesn't feel like a maintainable solution to me.
it is indeed one big file in our repository. why is it not maintainable? it's quite easy to get an overview in most editors (even neovim generates a TOC viewable by hitting gO in normal mode!).
i edit the file in my editor, but have a preview of the site open too, so I can judge the rendered output.
We have been doing this since the beginning for Fennel, and it honestly never occurred to me to do anything else; it's so obvious and easy: https://fennel-lang.org/tutorial Could probably still use a few more nav links in the shared header, but it's something pandoc can easily handle.
Including a single page that combines it all together is really smart tho; we should start doing that.
I also these days go for the popover API for sidebars. I like to use the HTML aside tag containing a nav for it as well instead of the div.
Where there any musings around using leaflet posts or other ATProto stuff for documentation?
How about Astro, I've used it many times now and it's really good for building multi-page websites. It also doesn't put any JS on the generated pages by default so it can be used as a glorified templating language for HTML.
It also has great support for markdown files and also extensions (I often need to render latex on my websites and it's just a matter of adding the right plugins). For searchability, I haven't used it but I also eared great things from pagefind as others have said and it should be compatible with Astro.
Astro default starter project required a ridiculous amount of boilerplate IIRC
I sketched this just to showcase a simple Astro project with a docs/ folder with nested documents and I don't think you can go much lower boilerplate than this (while still keeping all the control in what gets generated and put in the actual rendered html).
https://claude.ai/share/57174599-ea9f-4725-af81-0b64f4c5345e
P.S. Just to be clear I iterated a bit on the prompt just to show the core idea (this wasn't one-shot). I think this is already a reasonable starting point for a very minimal docs site.
Yes, that is reasonable. Thanks for proving me wrong. It's been a couple years since I used Astro. Perhaps it was the particular starter project that I was using that had a lot of boilerplate: https://github.com/satnaing/astro-paper
Maybe it's not fair to call it "boilerplate" because it's a pretty feature-rich starter project
I was surprised not to see Starlight on the comparison list. I needed to make a docs site recently and I made it on a fork of Starlight (in my fork I took out TS and replaced the markdown layer with my own document parser)
MkDocs and MdBook are still on my radar however, in case we need a bigger feature set.
Maybe look at zensical (mkdocs-material replacement) or antora, if you end up needing something beefier.
I've been using zensical in all new docs sites, and converting some older mkdocs-material sites. So far it seems very nice - fast, backwards compat with lots of mkdocs things, and receiving lots of updates.
I made one too that's meant to be used based on documentation written for man.sr.ht instances. (here's an example for the library I'm working on)
Also I went all the way with minimizing JavaScript usage it's used only for searching the docs. The TOC is built at site generation time based on headers and links in the files and presented using <details> with <summary> "hack"... sigh.