diff --git a/clap_derive/README.md b/clap_derive/README.md
index e0cc66ae..35c1fb9b 100644
--- a/clap_derive/README.md
+++ b/clap_derive/README.md
@@ -17,9 +17,9 @@ clap = "3"
 ```
 
 And then, in your rust file:
-```rust
+```rust,no_run
 use std::path::PathBuf;
-use clap::Parser;
+use clap::{Parser, ValueHint};
 
 /// A basic example
 #[derive(Parser, Debug)]
@@ -48,7 +48,7 @@ struct Opt {
     // the long option will be translated by default to kebab case,
     // i.e. `--nb-cars`.
     /// Number of cars
-    #[clap(short = "c", long)]
+    #[clap(short = 'c', long)]
     nb_cars: Option<i32>,
 
     /// admin_level to consider
@@ -67,7 +67,7 @@ fn main() {
 ```
 
 Using this example:
-```
+```bash
 $ ./basic
 error: The following required arguments were not provided:
     --output <output>
diff --git a/clap_derive/src/lib.rs b/clap_derive/src/lib.rs
index 41f6e21c..9f3eb8b0 100644
--- a/clap_derive/src/lib.rs
+++ b/clap_derive/src/lib.rs
@@ -14,11 +14,7 @@
 
 #![doc(html_logo_url = "https://clap.rs/images/media/clap.png")]
 #![doc(html_root_url = "https://docs.rs/clap_derive/3.0.0-beta.5")]
-
-//! This crate is custom derive for clap. It should not be used
-//! directly. See [clap documentation](http://docs.rs/clap)
-//! for the usage of `#[derive(Parser)]`.
-
+#![doc = include_str!("../README.md")]
 #![forbid(unsafe_code)]
 
 extern crate proc_macro;