mdBook VS MkDocs

I personally had the frustration that websites generated with [mdBook](https://github.com/rust-lang/mdBook) always displayed me the "Navy" theme. But I prefer the "Ayu" theme, therefore I always set the theme to "Ayu". But doing things per hand is not the way we do stuff around here, so I decided to write a small browser extension that applies the themes for me.

It's mdBook which is made in Rust and popular with Rust content https://rust-lang.github.io/mdBook/

I made a PDF generator for mdbook called mdbook-compress.

This makes me think, maybe I'll start using mdBook. I find it really comfortable to read and it's probably not too complicated to use.

I sync Obsidian with Git and use pandoc for book / ebook generation (or Foam with Visual Code might work too).

Scrivener can synchronise with Git too - albeit indirectly (it sync's with a folder & I use a simple script to keep it up to date)

If you need to organise research you can sync Wiki.js with Git.

However, Gitbook or mdBook might be easier to use for a single book project.

https://www.gitbook.com/

https://rust-lang.github.io/mdBook/

https://foambubble.github.io/foam/

https://js.wiki/

mdBook

+1 for Pandoc. I'll also add mdBook as an alternate for markdown to web version of ebooks (especially for search and themes).

I also don't mind using a Markdown editor + static site generator like mdBook - BookStack is where I'd have gone if I wanted something else

All credit goes to the mdbook people for this! I'm using it to turn Markdown text into HTML, complete with interactive playgrounds and all :-)

I tried most of the above mentioned and settled down with MkDocs for its simplicity. It produces static web pages so you can easily host it with any web server.

MkDocs is an open-source static site generator that is used to create documentation websites. It is written in Python and is built on top of the Jinja2 template engine. It uses Markdown files as the source for the documentation, and it generates a static HTML website that can be hosted on any web server.

https://www.mkdocs.org/ is what they are using.

Gitlab has implemented GitHub Pages feature, so KDE can do this. I don't know enough about Meson, but I have used MKDocs to generate websites for Node.js and Python projects.

Configured with a single YAML file, MKDocs is the fourth Markdown framework on my list, which falls in the category of SSG. Although there are not as many as in Hugo, MKDocs offers a few official themes and a number of third party themes. As a Python-based framework, you can use pip to install MKDocs plugins. You can follow this getting started guide for your first MKDocs project.

The second biggest one will be moving away from mkdocs and to Sphinx. During the process of the documentation overhaul, it has become clear that, while a great tool, mkdocs simply is not fit for the purpose of providing well structured, larger scale documentation. It definitely has its merits, and I would absolutely recommend it for someone looking for a simple tool to write not to complex docs, but if it's going to be more involved, mkdocs' shortcomings will catch up with you at some point.

You could try MkDocs, upload to GitHub, and host with GitHub Pages. This also allows you to use HTML and CSS if you want to customise the theme, and you can use Markdown for formatting any docs.

Mkdoks

Other people mentioned code comments and Markdown files, I'm inclined to agree.

I've used code comments pretty well to explain both non-trivial technical details, as give a quick rundown of business requirements that are the basis for some code existing, maybe with links back to an issue tracking system where more context is needed. Markdown files are better if you want to include images/videos/animations/diagrams and provide more context, or step by step instructions on how to do something, which is great because you can easily search through them, as they're just text. Code can typically explain what it does itself but not necessarily why, so it's great to have either of the tools at your disposal.

Of course, there's nothing wrong with external Wikis either, though some are implemented better than others IMHO.

Confluence is sometimes the only choice you get, so having it is better than having nothing.

GitLab and GitHub also have integrated Wikis, as do other solutions: https://docs.gitlab.com/ee/user/project/wiki and https://docs.github.com/en/communities/documenting-your-proj...

For ones to host separately, I've found BookStack to be pretty good in its simplicity/usability/performance: https://www.bookstackapp.com/

As for other solutions that are meant specifically for documentation, Read the Docs might be of appeal to some: https://readthedocs.org/

You can probably also use Sphinx (used by Flask): https://www.sphinx-doc.org/en/master/ or MkDocs: https://www.mkdocs.org/ or something else entirely.