Repository navigation
Integrate mdbook into rustdoc #66249
Description
It doesn't seem to be possible to include external markdown files without using include_file!. By this I mean your file would have to be included in your code hierarchy and it's not possible to have it as a separate hierarchy.
This could be useful for getting-started (even though usually included in the README), debugging-tips, or various tutorials.
A few ideas where this could be used:
- Be able to point rustdoc to some folder with markdown files, and it would render them all for the user to use freely in the code as normal links
- Added as an entry in the left column alongside Module, Structs, Enums, etc. Either a single entry to an index that the user would have to create, or a custom hierarchy that the user would define.
Reacted by Rob, Wojciech Kordalski, Marsh Ray, sme, Rodrigo and Jacob Pratt
Activity
Ppjet6 commentedon Nov 9, 2019
@kinnison, @GuillaumeGomez
steveklabnik commentedon Nov 11, 2019
There has long been a suggestion for "integrate mdbook into rustdoc and/or
cargo doc", but I cannot find the existing ticket I thought we had.GuillaumeGomez commentedon Nov 15, 2019
I think this is a good idea and something we might want to have on the long-term. However it brings some questions:
Ppjet6 commentedon Nov 15, 2019
@kinnison also raised the question of what to do with these links in reexported symbols (when they reference some file local to the repo that isn't in the one that reexports).
jyn514 commentedon Dec 15, 2020
This is
doc(include), right? If so I think it should be closed in favor of #44732.steveklabnik commentedon Jan 9, 2021
@jyn514 sorta; you can take it that way, or you can take it as "be able to make mdbooks with rustdoc too", that is, expanding rustdoc to not just be for API documentation, but for all documentation in your project.
[-]Add support for external markdown[/-][+]Integrate mdbook into rustdoc[/+]jyn514 commentedon Jan 9, 2021
Related: rust-lang/mdBook#1356
Susurrus commentedon Jan 9, 2021
There is a related bug to this against Cargo as well: rust-lang/cargo#739