I just like AsciiDoc a lot better for creating documentation. Also - Antora is very well thought out and brilliantly well supported tool. MkDocs gets the job done (I used it for a long time and I was reasonably happy with it), but doesn't hold a candle to Antora IMO. Probably it didn't also help that MkDocs on ReadTheDocs was constantly broken in one way or another. 😄

Yeah, with ReadTheDocs it was not fun using MkDocs. But since ditching RTD, MkDocs has served Calva very well. No idea what Antora is, but it probably is better. 😃

I evaluated Antora but according to polls, people by far favor a single page documentation site over a multipage thing with JS-based search. I've done the polls before and again last weekend and both times the results were unanimous...

A downside with that is that unfurls/social cards are document based. So all sections of the docs site get the same preview, same description, same meta. I don't want to make that trade off. And the MkDocs search is quite awesome.

I don't optimize docs for social media or mobile usage, but for developer-behind-the-laptop/pc usage

It has nothing to do with mobile usage. People, including developers-behind-the-laptop/pc, often share links to documentation with other developers-behind-the-laptop/pc over Slack, social media, etcetera. To me it is important that the preview gives reasonably good context, and I think ”Calva documentation” is too general, and prefer ”Calva Pretty Printing” or "Calva Getting Started”, etcetera, and not just about the title, but the description as well. Therefore I am not willing to make the tradeoff.

Like so: https://calva.io/api/

There are always trade-offs, and this preview context costs me in some ways. But to me it is important so I am paying those costs.

I don't see any preview ;)

I've done polls twice now and most people want a single page. I'm not the person reading the docs, but the person writing the docs, mostly, so I'll just go with what users prefer

> I don't see any preview 😉 Funny, but it looks like so for people who can see it. Similar on other platforms.

In my case I am often the person sharing links to the docs. 😃