My experience with most rust crates is that they do use separate markdown files for their big doc pages like readme and tutorial, getting started etc; and they

My experience with most rust crates is that they do use separate markdown files for their big doc pages like readme and tutorial, getting started etc; and they include (`!#doc["readme.md"]`, or something like that) these files in their source so that they're picked up by `cargo doc`. Only actual Rust items get directly-in-source-documentation -- again, in general. However I agree (I think) that markdown is not a great format for long form docs; you want something a bit more expressive (say, asciidoctor).