Any consensus on including long-form documentation in a crate?


I’d like to include some separate long-form documentation (in Markdown format) in a crate I’m developing. Ideally the source-code documentation could contain links to the long-form documentation residing in a top-level doc directory.

Until this kind of thing is officially supported, is there any community consensus on how to go about this?

I notice there are relevant RFC’s and discussions:

And the nom crate author has developed a tool for doing this:

Any advice or examples much appreciated,



I haven’t kept up to date with the community consensus (or where things are headed), but I just created a couple of sub-modules and wrote my documentation there. See the cookbook and tutorial sub-modules in the csv crate for instance:


ructe also hacks this with modules:


For now, IMHO, use mdbook, and publish to github pages.