diff --git a/src/lib.rs b/src/lib.rs
index 05e6184..58ca9be 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -32,14 +32,15 @@ pub struct Topic {
 
 #[derive(JsonSchema, Debug, Deserialize, Serialize)]
 pub struct Definition {
-    pub name: String,
     pub value: String,
+    #[serde(default, skip_serializing_if = "String::is_empty")]
+    pub description: String,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
     pub additional_info: Vec<String>,
 }
 
 #[derive(JsonSchema, Debug, Deserialize, Serialize)]
-pub struct ConfigDefault {
+pub struct Config {
     pub name: String,
     #[serde(rename = "type")]
     pub typ: String,
@@ -131,10 +132,10 @@ pub struct Project {
     pub description: String,
     #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
     pub topics: IndexMap<String, Topic>,
+    #[serde(default, skip_serializing_if = "IndexMap::is_empty")]
+    pub definitions: IndexMap<String, Definition>,
     #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub definitions: Vec<Definition>,
-    #[serde(default, skip_serializing_if = "Vec::is_empty")]
-    pub config_defaults: Vec<ConfigDefault>,
+    pub config: Vec<Config>,
 }
 
 #[must_use]
diff --git a/src/main.rs b/src/main.rs
index e75d017..403043c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -252,22 +252,21 @@ fn to_markdown(requirements: PathBuf, add_toc: bool) -> anyhow::Result<String> {
 
     if !project.definitions.is_empty() {
         output.push(s!("## Definitions"));
-        for definition in project.definitions {
-            output.push(format!(
-                "- {}: {}",
-                definition.name.trim(),
-                definition.value.trim()
-            ));
+        for (name, definition) in project.definitions {
+            output.push(format!("- {}: {}", name.trim(), definition.value.trim()));
+            if !definition.description.is_empty() {
+                output.push(format!("  - {}", definition.description));
+            }
             for info in definition.additional_info {
-                output.push(format!("  - {}", info.trim()))
+                output.push(format!("  - {}", info.trim()));
             }
         }
         output.push(nl());
     }
 
-    if !project.config_defaults.is_empty() {
-        output.push(s!("## Config Defaults"));
-        for default in project.config_defaults {
+    if !project.config.is_empty() {
+        output.push(s!("## Config"));
+        for default in project.config {
             output.push(format!("- **{}**", default.name.trim()));
             output.push(format!("  - Type: {}", default.typ.trim()));
             if let Some(unit) = default.unit {