diff --git a/crates/nuon/README.md b/crates/nuon/README.md
new file mode 100644
index 0000000000..d11aa8104c
--- /dev/null
+++ b/crates/nuon/README.md
@@ -0,0 +1,35 @@
+Support for the NUON format.
+
+The NUON format is a superset of JSON designed to fit the feel of Nushell.
+Some of its extra features are
+- trailing commas are allowed
+- commas are optional in lists
+- quotes are not required around keys or any _bare_ string that do not contain spaces
+- comments are allowed, though not preserved when using [`from_nuon`]
+
+## Example
+below is some data in the JSON format
+```json
+{
+    "name": "Some One",
+    "birth": "1970-01-01",
+    "stats": [
+      2544729499973429198,
+      687051042647753531,
+      6702443901704799912
+    ]
+}
+```
+
+and an equivalent piece of data written in NUON
+```nuon
+{
+    name: "Some One",       # the name of the person
+    birth: "1970-01-01",    # their date of birth
+    stats: [                # some dummy "stats" about them
+      2544729499973429198,
+      687051042647753531,
+      6702443901704799912, # note the trailing comma here...
+    ], # and here
+} # wait, are these comments in a JSON-like document?!?!
+```
diff --git a/crates/nuon/src/from.rs b/crates/nuon/src/from.rs
index 457b12d5f9..862b756db7 100644
--- a/crates/nuon/src/from.rs
+++ b/crates/nuon/src/from.rs
@@ -7,7 +7,9 @@ use std::sync::Arc;
 
 /// convert a raw string representation of NUON data to an actual Nushell [`Value`]
 ///
-/// > **Note**
+// WARNING: please leave the following two trailing spaces, they matter for the documentation
+// formatting
+/// > **Note**  
 /// > [`Span`] can be passed to [`from_nuon`] if there is context available to the caller, e.g. when
 /// > using this function in a command implementation such as
 /// [`from nuon`](https://www.nushell.sh/commands/docs/from_nuon.html).
diff --git a/crates/nuon/src/lib.rs b/crates/nuon/src/lib.rs
index cb86480580..891ccae62a 100644
--- a/crates/nuon/src/lib.rs
+++ b/crates/nuon/src/lib.rs
@@ -1,9 +1,4 @@
-//! Support for the NUON format.
-//!
-//! The NUON format is a superset of JSON designed to fit the feel of Nushell.
-//! Some of its extra features are
-//! - trailing commas are allowed
-//! - quotes are not required around keys
+#![doc = include_str!("../README.md")]
 mod from;
 mod to;
 
diff --git a/crates/nuon/src/to.rs b/crates/nuon/src/to.rs
index 30fe2664a2..8aeb47a097 100644
--- a/crates/nuon/src/to.rs
+++ b/crates/nuon/src/to.rs
@@ -39,7 +39,9 @@ pub enum ToStyle {
 
 /// convert an actual Nushell [`Value`] to a raw string representation of the NUON data
 ///
-/// > **Note**
+// WARNING: please leave the following two trailing spaces, they matter for the documentation
+// formatting
+/// > **Note**  
 /// > a [`Span`] can be passed to [`to_nuon`] if there is context available to the caller, e.g. when
 /// > using this function in a command implementation such as [`to nuon`](https://www.nushell.sh/commands/docs/to_nuon.html).
 ///