Coming from #MkDocs on #ReadTheDocs , I think about migrating our projects user manual to #Asciidoc using #asciidoctor and/or #antora .
But I wonder if there is a service like #readthedocs for #asciidoc based manuals available for #OpenSource or #foss projects.
Important is that those platforms do support @Codeberg (#forgejo aka #gita ) code hosting, instead of Microsoft GitHub.
@jwildeboer
That is not just a good tip, but actually a hard requirement in many style guides for technical documentation.
For HTML output, you can avoid having to remember it via something like this:
https://squidfunk.github.io/mkdocs-material/reference/tooltips/?h=abbreviation#adding-abbreviations
@kobilacroix if you just want a cheap & simple website, that is still easy.
One option beyond "Overkill-#CMS||es" like #WordPress are "#OfflineCMS|es" like #MkDocs-Material that allow for simple #Markdown editing and clean #HTML whilst offering #search functionality.
Also there are more #Webhosters than ever before...
"Most guides to docs like code, even the ones for non-devs, assume you have some developer knowledge: maybe you're already using version control, or you've encountered build pipelines before, or you're working alongside developers.
This guide is for the people who read that paragraph and wished it came with a glossary. This is docs like code for people who don't know what git is and have never installed VS Code.
This post explains terminology and concepts, to help you get a mental model of what's going on. If you prefer to dive in and pick up concepts as you go, skip straight to the tips in How to learn, and come back to the conceptual info as needed."
#discord IS LITERALLY THE PROBLEM!
It's worse than any #IRC, #Mumble or even the old #TeamSpeak & #Skype for that matter.
It combines the disadvantages of #Forum, #paywalled #documentation, #chat and #voicechat with 0 redeeming qualities (unlike #Zulip & Mumble & #XMPP+#OMEMO) it's just an #InformationBlackhole!
I'm shure fecking #dread has better moderation and I'd rather use #MicrosoftTeams + #Slack cuz those at least have proper #moderation tools.
Case in point: I'd rather #SelfHost all my comms infrastructure than to ever use something like Discord or any other #GDPR-violating SaaS that is just enshittification.
I'd rather recommend people to instead choose a tool that does everything but horrible to go with multiple smaller & good tools
Check @alternativeto and @european_alternatives for options.
Shoutout to @squidfunk for making Material for MkDocs which comes with a metric ton of #QualityOfLife improvements like being easily able to self-host all assets and thus comply with #privacy #laws whilst being as easy to setup as the regular #MkDocs.
@memesmadetorunonlinux you know what's real #GigaChad in terms of #Presentations?
For everyone else there's #MkDocs (or rather #MkDocsMaterial) for making beautiful #HTML presentations...
@radis_noir perso, après avoir testé plusieurs solutions, la plus simple me semble être #MKDocs (http://www.mkdocs.org/). Je l'utilise pour https://infolit.be
J'utilise le template Cinder et ai un peu modifié la CSS github à ma sauce ... (et je ne suis pas du tout un geek !).
@sbrl and I guess #LibreOffice Draw isn't an option?
Thinking about transitioning my #blogging from #nikola to #mkdocs
Nikola is great but I've always felt like writing in Markdown is an also ran use case, as its native lingua franca is my long time nemesis #restructuredtext (Hate hate HATE! :) ).
mkdocs is built from the ground up to be super simple. Give it a pile of Markdown and it'll generate a site. There's a nice plugin for generating a blog:
https://github.com/squidfunk/mkdocs-material/blob/master/docs/setup/setting-up-a-blog.md
I've written a guide to building a highly customisable, lightweight, secure, and performant static site using #MkDocs, #NGINX and #Docker: https://matthew-shaw.github.io/blog/2024/11/04/building-a-static-site-with-mkdocs-nginx-and-docker/
A small pre-announcement.
I am currently working on a brand new sub-site I have dubbed "DarkXero's Bytes" which will eventually be replacing the current "Journal" site. It uses something simple called #MKDocs. Here's a preview. Still work in progress as I populate it with some content.. #Blog #Private #Thoughts #FOSS #Developer #Maintainer #Linux
@mook @MastodonEngineering EXACTLY THIS is why I think a "#Webhoster-only" functional #ActivityPub server is kinda important.
And for what Mastodon does, it feels quite overengineered and overcomplex, but then again I'm used to #MkDocs and other, "#offline-#CMS|es" that do just work and are kinda essential for stuff on @torproject / #Tor because noone there uses #JavaScript and enabling #JS is discouraged by #TorBrowser for all the right reasons...
I should take a closer look at #streams once I have time for that...
XeroLinux 