diff --git a/text/3123-rustdoc-scrape-examples.md b/text/3123-rustdoc-scrape-examples.md
new file mode 100644
index 00000000000..f14e5b11fee
--- /dev/null
+++ b/text/3123-rustdoc-scrape-examples.md
@@ -0,0 +1,125 @@
+- Feature Name: `rustdoc_scrape_examples`
+- Start Date: 2021-05-09
+- RFC PR: [rust-lang/rfcs#3123](https://github.com/rust-lang/rfcs/pull/3123)
+- Rust Issue: [rust-lang/rust#0000](https://github.com/rust-lang/rust/issues/0000)
+
+# Summary
+[summary]: #summary
+
+This RFC proposes an extension to Rustdoc that automatically scrapes code examples from the project's `examples/` directory.
+
+Check out a live demo here: https://willcrichton.net/example-analyzer/warp/trait.Filter.html#method.and
+
+# Motivation
+[motivation]: #motivation
+
+Code examples are an important tool for programmers to understand how a library works. Examples are **concrete** and **contextual**: they reference actual values rather than abstract parameters, and they show how to use a function in the context of the code around it.
+
+As a parable of the value of examples, I recently did a small user study where I observed two Rust programmers learning to use the [warp](https://github.com/seanmonstar/warp) library for a basic task. Warp is designed around a generic [`Filter`](https://docs.rs/warp/0.3.1/warp/trait.Filter.html) abstraction. Both participants found the documentation for `Filter` methods to be both imposing and too generic to be useful. For instance, [`Filter::and`](https://docs.rs/warp/0.3.1/warp/trait.Filter.html#method.and):
+
+
+
+
+The repo authors also included a code example. But neither participant could understand the example because it lacked context.
+
+
+
+The participant who was less familiar with Rust struggled to read the documentation and failed to accomplish the task. By contrast, the participant who was more familiar with Rust knew to look in the `examples/` directory, where they found a wealth of examples for each function that complemented the documentation. For instance, [`rejection.rs`](https://github.com/seanmonstar/warp/blob/bf8bfc4134035dbff882f9b26cb9d1aa57f2c338/examples/rejections.rs) shows the usage of `and` in combination with `map`:
+
+```rust
+let math = warp::path!("math" / u16);
+let div_with_header = math
+ .and(warp::get())
+ .and(div_by())
+ .map(|num: u16, denom: NonZeroU16| {
+ warp::reply::json(&Math {
+ op: format!("{} / {}", num, denom),
+ output: num / denom.get(),
+ })
+ });
+```
+
+The goal of this RFC is to bridge the gap between automatically generated documentation and code examples by helping users find relevant examples within Rustdoc.
+
+# Guide-level explanation
+[guide-level-explanation]: #guide-level-explanation
+
+The `scrape-examples` feature of Rustdoc finds examples of code where a particular function is called. For example, if we are documenting [`Filter::and`](https://willcrichton.net/example-analyzer/warp/trait.Filter.html#method.and), and a file [`examples/returning.rs`](https://github.com/seanmonstar/warp/tree/bf8bfc4134035dbff882f9b26cb9d1aa57f2c338/examples/returning.rs) contains a call to `and`, then the corresponding Rustdoc documentation looks like this:
+
+
+
+
+
+After the user-provided documentation in the doc-comment, `scrape-examples` inserts a code example (if one exists). The code example shows a window into the source file with the function call highlighted in yellow. The icons in the top-right of the code viewer allow the user to expand the code sample to the full file, or to navigate through other calls in the same file. The link above the example goes to the full listing in Rustdoc's generated `src/` directory, similar to other `[src]` links.
+
+Additionally, the user can click "More examples" to see every example from the `examples/` directory, like this:
+
+
+
+To use the `scrape-examples` feature, simply add the `--scrape-examples` flag like so:
+
+```
+cargo doc --scrape-examples
+```
+
+
+# Reference-level explanation
+
+I have implemented a prototype of the `scrape-examples` feature as modifications to rustdoc and cargo. You can check out the draft PRs:
+* rustdoc: https://github.com/rust-lang/rust/pull/85833
+* cargo: https://github.com/rust-lang/cargo/pull/9525
+
+The feature uses the following high-level flow, with some added technical details as necessary.
+
+1. The user gives `--scrape-examples` as an argument to `cargo doc`.
+2. Cargo runs the equivalent of `cargo rustdoc --examples` ([source](https://github.com/willcrichton/cargo/blob/9c9f86772cbcf49f77119b7471021989e72c9936/src/cargo/ops/cargo_compile.rs#L596-L655)).
+ * Specifically, when constructing the `BuildContext`, Cargo will now recursively invoke `rustdoc` on all files matching the `--examples` filter.
+ * Each invocation includes a flag `--scrape-examples