From 66c26750c7f163ffc646e3b162911c05268f4118 Mon Sep 17 00:00:00 2001
From: "Kyle J. McKay" <mackyle@gmail.com>
Date: Thu, 3 Sep 2015 00:56:30 -0700
Subject: [PATCH] Markdown.pl: support setext-style third level headers and
 overlines

Using a '~' underline will now generate an h3 header.

A preceding overline made with the same character as the underline
is now permitted.

Signed-off-by: Kyle J. McKay <mackyle@gmail.com>
---
 Markdown.pl | 11 +++++++++--
 basics.text | 15 +++++++++++----
 syntax.text | 21 +++++++++++++++++++--
 3 files changed, 39 insertions(+), 8 deletions(-)

diff --git a/Markdown.pl b/Markdown.pl
index 8cf2418..17ffce5 100755
--- a/Markdown.pl
+++ b/Markdown.pl
@@ -730,14 +730,21 @@ sub _DoHeaders {
 	#	  Header 2
 	#	  --------
 	#
-	$text =~ s{ ^(.+)[ \t]*\n=+[ \t]*\n+ }{
+	#	  Header 3
+	#	  ~~~~~~~~
+	#
+	$text =~ s{ ^(?:=+[ \t]*\n)?(.+)[ \t]*\n=+[ \t]*\n+ }{
 		"<h1>"  .  _RunSpanGamut($1)  .  "</h1>\n\n";
 	}egmx;
 
-	$text =~ s{ ^(.+)[ \t]*\n-+[ \t]*\n+ }{
+	$text =~ s{ ^(?:-+[ \t]*\n)?(.+)[ \t]*\n-+[ \t]*\n+ }{
 		"<h2>"  .  _RunSpanGamut($1)  .  "</h2>\n\n";
 	}egmx;
 
+	$text =~ s{ ^(?:~+[ \t]*\n)?(.+)[ \t]*\n~+[ \t]*\n+ }{
+		"<h3>"  .  _RunSpanGamut($1)  .  "</h3>\n\n";
+	}egmx;
+
 
 	# atx-style headers:
 	#	# Header 1
diff --git a/basics.text b/basics.text
index 87c6ff5..4a0b152 100644
--- a/basics.text
+++ b/basics.text
@@ -41,8 +41,9 @@ considered blank.) Normal paragraphs should not be indented with
 spaces or tabs.
 
 Markdown offers two styles of headers: *Setext* and *atx*.
-Setext-style headers for `<h1>` and `<h2>` are created by
-"underlining" with equal signs (`=`) and hyphens (`-`), respectively.
+Setext-style headers for `<h1>`, `<h2>` and `<h3>` are created by
+"underlining" with equal signs (`=`), hyphens (`-`) and tildes (`~`)
+respectively.  An optional matching "overline" may precede the header.
 To create an atx-style header, you put 1-6 hash marks (`#`) at the
 beginning of the line -- the number of hashes equals the resulting
 HTML header level.
@@ -51,12 +52,16 @@ Blockquotes are indicated using email-style '`>`' angle brackets.
 
 Markdown:
 
+    ====================
     A First Level Header
     ====================
     
     A Second Level Header
     ---------------------
 
+    A Third Level Header
+    ~~~~~~~~~~~~~~~~~~~~
+
     Now is the time for all good men to come to
     the aid of their country. This is just a
     regular paragraph.
@@ -64,7 +69,7 @@ Markdown:
     The quick brown fox jumped over the lazy
     dog's back.
     
-    ### Header 3
+    ### Header 4
 
     > This is a blockquote.
     > 
@@ -79,6 +84,8 @@ Output:
     
     <h2>A Second Level Header</h2>
     
+    <h3>A Third Level Header</h3>
+    
     <p>Now is the time for all good men to come to
     the aid of their country. This is just a
     regular paragraph.</p>
@@ -86,7 +93,7 @@ Output:
     <p>The quick brown fox jumped over the lazy
     dog's back.</p>
     
-    <h3>Header 3</h3>
+    <h4>Header 3</h4>
     
     <blockquote>
         <p>This is a blockquote.</p>
diff --git a/syntax.text b/syntax.text
index 0a5d63d..d23a051 100644
--- a/syntax.text
+++ b/syntax.text
@@ -212,7 +212,8 @@ work best -- and look better -- when you format them with hard breaks.
 Markdown supports two styles of headers, [Setext] [1] and [atx] [2].
 
 Setext-style headers are "underlined" using equal signs (for first-level
-headers) and dashes (for second-level headers). For example:
+headers), dashes (for second-level headers) and tildes (for third-level
+headers). For example:
 
     This is an H1
     =============
@@ -220,7 +221,23 @@ headers) and dashes (for second-level headers). For example:
     This is an H2
     -------------
 
-Any number of underlining `=`'s or `-`'s will work.
+    This is an H3
+    ~~~~~~~~~~~~~
+
+Any number of underlining `=`'s, `-`'s or `~`'s will work.  An optional
+matching "overline" may precede the header like so:
+
+    =============
+    This is an H1
+    =============
+
+    -------------
+    This is an H2
+    -------------
+
+    ~~~~~~~~~~~~~
+    This is an H3
+    ~~~~~~~~~~~~~
 
 Atx-style headers use 1-6 hash characters at the start of the line,
 corresponding to header levels 1-6. For example: