Index: readme/class-parser.php
===================================================================
--- readme/class-parser.php	(revision 3820)
+++ readme/class-parser.php	(working copy)
@@ -67,6 +67,11 @@
 	public $screenshots = array();
 
 	/**
+	 * @var array
+	 */
+	public $faq = array();
+
+	/**
 	 * These are the readme sections that we expect.
 	 *
 	 * @var array
@@ -286,36 +291,20 @@
 
 		// Parse out the Upgrade Notice section into it's own data.
 		if ( isset( $this->sections['upgrade_notice'] ) ) {
-			$lines   = explode( "\n", $this->sections['upgrade_notice'] );
-			$version = null;
-			$current = '';
-			while ( ( $line = array_shift( $lines ) ) !== null ) {
-				$trimmed = trim( $line );
-				if ( empty( $trimmed ) ) {
-					continue;
-				}
-
-				if ( '=' === $trimmed[0] || '#' === $trimmed[0] ) {
-					if ( ! empty( $current ) ) {
-						$this->upgrade_notice[ $version ] = $this->sanitize_text( trim( $current ) );
-					}
-
-					$current = '';
-					$version = trim( $line, "#= \t" );
-					continue;
-				}
-
-				$current .= $line . "\n";
-			}
-			if ( ! empty( $version ) && ! empty( $current ) ) {
-				$this->upgrade_notice[ $version ] = $this->sanitize_text( trim( $current ) );
-			}
+			$this->upgrade_notice = $this->parse_section( $this->sections['upgrade_notice'] );
 			unset( $this->sections['upgrade_notice'] );
 		}
 
+		// Display FAQs as a definition list.
+		if ( isset( $this->sections['faq'] ) ) {
+			$this->faq = $this->parse_section( $this->sections['faq'] );
+			$this->sections['faq'] = '';
+		}
+
 		// Markdownify!
 		$this->sections       = array_map( array( $this, 'parse_markdown' ), $this->sections );
 		$this->upgrade_notice = array_map( array( $this, 'parse_markdown' ), $this->upgrade_notice );
+		$this->faq            = array_map( array( $this, 'parse_markdown' ), $this->faq );
 
 		// Sanitize and trim the short_description to match requirements.
 		$this->short_description = $this->sanitize_text( $this->short_description );
@@ -334,6 +323,26 @@
 			unset( $this->sections['screenshots'] );
 		}
 
+		if ( ! empty( $this->faq ) ) {
+			$plain_text = false;
+
+			foreach( $this->faq as $question => $answer ) {
+				if ( empty( $question ) ) {
+					$this->sections['faq'] = $answer;
+					$plain_text            = true;
+					break;
+				}
+
+				$this->sections['faq'] .= "<dt>{$question}</dt>\n<dd>{$answer}</dd>\n";
+			}
+
+			if ( ! $plain_text ) {
+				$this->sections['faq'] = "<dl>{$this->sections['faq']}</dl>\n";
+			}
+
+			unset( $this->faq );
+		}
+
 		// Filter the HTML.
 		$this->sections = array_map( array( $this, 'filter_text' ), $this->sections );
 
@@ -413,6 +422,9 @@
 			'strong'     => true,
 			'ul'         => true,
 			'ol'         => true,
+			'dl'         => true,
+			'dt'         => true,
+			'dd'         => true,
 			'li'         => true,
 			'h3'         => true,
 			'h4'         => true,
@@ -494,6 +506,40 @@
 		return $stable_tag;
 	}
 
+	protected function parse_section( $lines ) {
+		$key = $value = '';
+		$return = array();
+
+		if ( ! is_array( $lines ) ) {
+			$lines = explode( "\n", $lines );
+		}
+
+		while ( ( $line = array_shift( $lines ) ) !== null ) {
+			$trimmed = trim( $line );
+			if ( empty( $trimmed ) ) {
+				continue;
+			}
+
+			if ( in_array( $trimmed[0], array( '=', '#', '*' ), true ) ) {
+				if ( ! empty( $value ) ) {
+					$return[ $key ] = $this->sanitize_text( trim( $value ) );
+				}
+
+				$value = '';
+				$key   = trim( $line, "=#* \t" );
+				continue;
+			}
+
+			$value .= $line . "\n";
+		}
+
+		if ( ! empty( $key ) || ! empty( $value ) ) {
+			$return[ $key ] = $this->sanitize_text( trim( $value ) );
+		}
+
+		return $return;
+	}
+
 	/**
 	 * @param string $text
 	 * @return string