diff --git a/docs/1-deriving.md b/docs/1-deriving.md
index 90cee07..93cb54d 100644
--- a/docs/1-deriving.md
+++ b/docs/1-deriving.md
@@ -4,6 +4,7 @@ title: Deriving JsonSchema
 nav_order: 2
 has_children: true
 has_toc: false
+permalink: /deriving
 ---
 
 # Deriving JsonSchema
diff --git a/docs/1.1-attributes.md b/docs/1.1-attributes.md
index b72344c..a81e8a0 100644
--- a/docs/1.1-attributes.md
+++ b/docs/1.1-attributes.md
@@ -3,6 +3,7 @@ layout: default
 title: Attributes
 parent: Deriving JsonSchema
 nav_order: 1
+permalink: /deriving/attributes
 ---
 
 <style>
@@ -40,7 +41,7 @@ Serde also allows setting `#[serde(...)]` attributes which change how types are
 `#[serde(rename = "name")]` / `#[schemars(rename = "name")]`
 </h3>
 
-Set on a struct, enum, field or variant to use the given name in the generated schema instead of the Rust name. When used on a struct or enum, the given name will be used as the title for root schemas, and as the schema identifier for schemas referenced from another schema's `$ref` property.
+Set on a struct, enum, field or variant to use the given name in the generated schema instead of the Rust name. When used on a struct or enum, the given name will be used as the title for root schemas, and the key within the root's `definitions` property for subschemas.
 
 If set on a struct or enum with generic type parameters, then the given name may contain them enclosed in curly braces (e.g. `{T}`) and they will be replaced with the concrete type names when the schema is generated.
 
diff --git a/docs/2-implementing.md b/docs/2-implementing.md
index c35748b..2242758 100644
--- a/docs/2-implementing.md
+++ b/docs/2-implementing.md
@@ -2,6 +2,7 @@
 layout: default
 title: Implementing JsonSchema
 nav_order: 3
+permalink: /implementing
 ---
 
 # Implementing JsonSchema
diff --git a/docs/3-generating.md b/docs/3-generating.md
index 7b90d64..7c45603 100644
--- a/docs/3-generating.md
+++ b/docs/3-generating.md
@@ -2,6 +2,7 @@
 layout: default
 title: Generating Schemas
 nav_order: 4
+permalink: /generating
 ---
 
 # Generating Schemas
diff --git a/docs/4-features.md b/docs/4-features.md
index 5ebc637..70e1a0c 100644
--- a/docs/4-features.md
+++ b/docs/4-features.md
@@ -2,6 +2,7 @@
 layout: default
 title: Feature Flags
 nav_order: 5
+permalink: /features
 ---
 
 # Feature Flags and Optional Dependencies
diff --git a/docs/404.html b/docs/404.html
index b178af5..0f623a0 100644
--- a/docs/404.html
+++ b/docs/404.html
@@ -1,5 +1,5 @@
 ---
-permalink: /404.html
+permalink: /404
 layout: default
 nav_exclude: true
 ---
diff --git a/docs/5-examples.md b/docs/5-examples.md
index c0a2848..93734c5 100644
--- a/docs/5-examples.md
+++ b/docs/5-examples.md
@@ -3,6 +3,7 @@ layout: default
 title: Examples
 nav_order: 6
 has_children: true
+permalink: /examples
 ---
 
 # Examples
\ No newline at end of file
diff --git a/schemars/src/lib.rs b/schemars/src/lib.rs
index 1897c22..93d0d4e 100644
--- a/schemars/src/lib.rs
+++ b/schemars/src/lib.rs
@@ -231,7 +231,7 @@ pub trait JsonSchema {
 
     /// The name of the generated JSON Schema.
     ///
-    /// This is used as the title for root schemas, and the key within the `definitions` property for subschemas.
+    /// This is used as the title for root schemas, and the key within the root's `definitions` property for subschemas.
     fn schema_name() -> String;
 
     /// Generates a JSON Schema for this type.