diff --git a/src/main.rs b/src/main.rs
index afe447b..d5988e6 100755
--- a/src/main.rs
+++ b/src/main.rs
@@ -191,15 +191,12 @@ fn extract_peripheral(args: ExtractPeripheral) -> Result<()> {
 
     // Descriptions in SVD's contain a lot of noise and weird formatting. Clean them up.
     let description_cleanups = [
-        // Fix weird newline spam in descriptions.
-        (Regex::new("[ \n]+").unwrap(), " "),
-        // Fix weird tab and cr spam in descriptions.
-        (Regex::new("[\r\t]+").unwrap(), " "),
-        // Replace double-space (end of sentence) with period.
-        (
-            Regex::new(r"(?<first_sentence>.*?)[\s]{2}(?<next_sentence>.*)").unwrap(),
-            "$first_sentence. $next_sentence",
-        ),
+        // Replace consecutive LF and whitespace with one newline/whitespace.
+        (Regex::new("([ \n]){2,}").unwrap(), "$1"),
+        // Replace (consecutive) CR with (one) LF.
+        (Regex::new("\r+").unwrap(), "\n"),
+        // Replace (consecutive) TAB with (one) whitespace
+        (Regex::new("\t+").unwrap(), " "),
         // Make sure every description ends with a period.
         (
             Regex::new(r"(?<full_description>.*)(?<last_character>[\s'[^\.\s']])$").unwrap(),
diff --git a/src/util.rs b/src/util.rs
index 36799c9..7b874cf 100644
--- a/src/util.rs
+++ b/src/util.rs
@@ -310,12 +310,28 @@ pub fn relative_path(a: &str, b: &str) -> TokenStream {
     res
 }
 
+// If a document contains newline(either hardcode newline or escape sequence),
+// convert each newline into a valid markdown linebreak (but not the last line end).
 pub fn doc(doc: &Option<String>) -> TokenStream {
     if let Some(doc) = doc {
-        let doc = doc.replace("\\n", "\n");
-        let doc = respace(&doc);
-        let doc = escape_brackets(&doc);
-        quote!(#[doc=#doc])
+        let mut doc = doc.replace("\\r", "\n");
+        doc = doc.replace("\\n", "\n");
+
+        let doc_lines: Vec<_> = doc.split('\n').skip_while(|v| v.is_empty()).collect();
+
+        let mut markdown_doc = String::new();
+
+        for (index, line) in doc_lines.iter().enumerate() {
+            let mut line = respace(line);
+            line = escape_brackets(&line);
+            // save a lot of whitespace for one-line doc
+            if index != doc_lines.len() - 1 {
+                line.push_str("  \n");
+            }
+            markdown_doc.push_str(&line);
+        }
+
+        quote!(#[doc=#markdown_doc])
     } else {
         quote!()
     }