Fork me on GitHub

@t is currently investigating mkdocs for documentation for nbb. @pez and @ericdallo have good experience with this. It was recommended by @bozhidar to PEZ, but bozhidar is now using something else. Any reason for the switch?


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.


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. 😃


for lsp-mode, there is even custom elisp code that generates all functions and variables docs programatically and convert to markdown to be on the webpage

👀 1

Ohhh, I must fix some of that generated content for Calva as well. It's a PITA with the API docs!


> custom elisp code that generates all functions and variables docs programatically sounds a bit like maybe?


For clojure projects sounds good @borkdude