How to include an arbitrary markdown file as a documentation attribute?

Question

If the readme Cargo.toml key is set, doc.rs renders the README on the crate's index page. Is there a way to emulate this when running cargo doc locally?

If I add:

#![doc = r###"contents
of
README.md
here
"###]

as a literal, I get the behaviour I'm looking for, but inlining a copy of my whole README.md is pretty inconvenient for making updates.

I tried:

#![doc = include!("README.md")]

but this gives an error:

error: unexpected token: `include`
 --> src/lib.rs:3:10
  |
3 | #![doc = include!("README.md")]
  |          ^^^^^^^

Answer 1

Update as of Rust 1.54.0:

#![doc = include_str!("path/to/docs.md")]

---

Original answer:

There is an unstable feature, external-doc, which enables this:

Example usage (nightly-only):

#![feature(external_doc)]

#![doc(include = "../README.md")]