Markdown writer: default to using ATX headings.

Previously we used Setext (underlined) headings by default.
The default is now ATX (`##` style).

* Add the `--markdown-headings=atx|setext` option.
* Deprecate `--atx-headers`.
* Add constructor 'ATXHeadingInLHS` constructor to `LogMessage` [API change].
* Support `markdown-headings` in defaults files.
* Document new options in MANUAL.

Closes #6662.

MANUAL.txt

@@ -970,14 +970,19 @@ header when requesting a document from a URL:
     current section, or the document. The default is
     `document`. Currently only affects the markdown writer.
 
+`--markdown-headings=setext`|`atx
+
+:   Specify whether to use ATX-style (`#`-prefixed) or
+    Setext-style (underlined) headings for level 1 and 2
+    headings in Markdown output.  (ATX is the default.)
+    ATX headings are always used for levels 3+.
+    This option also affects Markdown cells in `ipynb` output.
+
 `--atx-headers`
 
-:   Use ATX-style headings in Markdown output. The default is
+:   *Deprecated synonym for `--markdown-headings=atx`.*
-    to use setext-style headings for levels 1 to 2, and then ATX headings.
-    (Note: for `gfm` output, ATX headings are always used.)
-    This option also affects markdown cells in `ipynb` output.
 
-`--top-level-division=[default|section|chapter|part]`
+`--top-level-division=default`|`section`|`chapter`|`part`
 
 :   Treat top-level headings as the given division type in LaTeX, ConTeXt,
     DocBook, and  TEI output. The hierarchy order is part, chapter, then section;
@@ -1624,7 +1629,7 @@ epub-cover-image: cover.jpg
 reference-links: true
 # block, section, or document
 reference-location: block
-atx-headers: false
+markdown-headings: setext
 
 # accept, reject, or all
 track-changes: accept

src/Text/Pandoc/App/CommandLineOptions.hs

@@ -529,9 +529,26 @@ options =
 
     , Option "" ["atx-headers"]
                  (NoArg
-                  (\opt -> return opt { optSetextHeaders = False } ))
+                  (\opt -> do
+                    deprecatedOption "--atx-headers"
+                      "use --markdown-headings=atx"
+                    return opt { optSetextHeaders = False } ))
                  "" -- "Use atx-style headers for markdown"
 
+    , Option "" ["markdown-headings"]
+                  (ReqArg
+                    (\arg opt -> do
+                      headingFormat <- case arg of
+                        "setext" -> pure True
+                        "atx" -> pure False
+                        _ -> E.throwIO $ PandocOptionError $ T.pack
+                          ("Unknown markdown heading format: " ++ arg ++
+                            ". Expecting atx or setext")
+                      pure opt { optSetextHeaders = headingFormat }
+                    )
+                  "setext|atx")
+                  ""
+
     , Option "" ["listings"]
                  (NoArg
                   (\opt -> return opt { optListings = True }))

src/Text/Pandoc/App/Opt.hs

@@ -330,6 +330,12 @@ doOpt (k',v) = do
       parseYAML v >>= \x -> return (\o -> o{ optSlideLevel = x })
     "atx-headers" ->
       parseYAML v >>= \x -> return (\o -> o{ optSetextHeaders = not x })
+    "markdown-headings" ->
+      parseYAML v >>= \x -> return (\o ->
+        case (T.toLower x) of
+          "atx"    -> o{ optSetextHeaders = False }
+          "setext" -> o{ optSetextHeaders = True }
+          _        -> o)
     "ascii" ->
       parseYAML v >>= \x -> return (\o -> o{ optAscii = x })
     "default-image-extension" ->
@@ -469,7 +475,7 @@ defaultOpts = Opt
     , optPdfEngine             = Nothing
     , optPdfEngineOpts         = []
     , optSlideLevel            = Nothing
-    , optSetextHeaders         = True
+    , optSetextHeaders         = False
     , optAscii                 = False
     , optDefaultImageExtension = ""
     , optExtractMedia          = Nothing

src/Text/Pandoc/Logging.hs

@@ -31,6 +31,7 @@ import Data.Aeson.Encode.Pretty (Config (..), defConfig, encodePretty',
 import qualified Data.ByteString.Lazy as BL
 import Data.Data (Data, toConstr)
 import qualified Data.Text as Text
+import Data.Text (Text)
 import Data.Typeable (Typeable)
 import GHC.Generics (Generic)
 import Text.Pandoc.Definition
@@ -59,45 +60,46 @@ instance FromYAML Verbosity where
          _         -> mzero
 
 data LogMessage =
-    SkippedContent Text.Text SourcePos
+    SkippedContent Text SourcePos
-  | IgnoredElement Text.Text
+  | IgnoredElement Text
-  | DuplicateLinkReference Text.Text SourcePos
+  | DuplicateLinkReference Text SourcePos
-  | DuplicateNoteReference Text.Text SourcePos
+  | DuplicateNoteReference Text SourcePos
-  | NoteDefinedButNotUsed Text.Text SourcePos
+  | NoteDefinedButNotUsed Text SourcePos
-  | DuplicateIdentifier Text.Text SourcePos
+  | DuplicateIdentifier Text SourcePos
-  | ReferenceNotFound Text.Text SourcePos
+  | ReferenceNotFound Text SourcePos
-  | CircularReference Text.Text SourcePos
+  | CircularReference Text SourcePos
-  | UndefinedToggle Text.Text SourcePos
+  | UndefinedToggle Text SourcePos
-  | ParsingUnescaped Text.Text SourcePos
+  | ParsingUnescaped Text SourcePos
-  | CouldNotLoadIncludeFile Text.Text SourcePos
+  | CouldNotLoadIncludeFile Text SourcePos
-  | MacroAlreadyDefined Text.Text SourcePos
+  | MacroAlreadyDefined Text SourcePos
   | InlineNotRendered Inline
   | BlockNotRendered Block
-  | DocxParserWarning Text.Text
+  | DocxParserWarning Text
-  | IgnoredIOError Text.Text
+  | IgnoredIOError Text
-  | CouldNotFetchResource Text.Text Text.Text
+  | CouldNotFetchResource Text Text
-  | CouldNotDetermineImageSize Text.Text Text.Text
+  | CouldNotDetermineImageSize Text Text
-  | CouldNotConvertImage Text.Text Text.Text
+  | CouldNotConvertImage Text Text
-  | CouldNotDetermineMimeType Text.Text
+  | CouldNotDetermineMimeType Text
-  | CouldNotConvertTeXMath Text.Text Text.Text
+  | CouldNotConvertTeXMath Text Text
-  | CouldNotParseCSS Text.Text
+  | CouldNotParseCSS Text
-  | Fetching Text.Text
+  | Fetching Text
-  | Extracting Text.Text
+  | Extracting Text
-  | NoTitleElement Text.Text
+  | NoTitleElement Text
   | NoLangSpecified
-  | InvalidLang Text.Text
+  | InvalidLang Text
-  | CouldNotHighlight Text.Text
+  | CouldNotHighlight Text
-  | MissingCharacter Text.Text
+  | MissingCharacter Text
-  | Deprecated Text.Text Text.Text
+  | Deprecated Text Text
-  | NoTranslation Text.Text
+  | NoTranslation Text
-  | CouldNotLoadTranslations Text.Text Text.Text
+  | CouldNotLoadTranslations Text Text
-  | UnusualConversion Text.Text
+  | UnusualConversion Text
-  | UnexpectedXmlElement Text.Text Text.Text
+  | UnexpectedXmlElement Text Text
-  | UnknownOrgExportOption Text.Text
+  | UnknownOrgExportOption Text
-  | CouldNotDeduceFormat [Text.Text] Text.Text
+  | CouldNotDeduceFormat [Text] Text
   | RunningFilter FilePath
   | FilterCompleted FilePath Integer
-  | CiteprocWarning Text.Text
+  | CiteprocWarning Text
+  | ATXHeadingInLHS Int Text
   deriving (Show, Eq, Data, Ord, Typeable, Generic)
 
 instance ToJSON LogMessage where
@@ -224,8 +226,11 @@ instance ToJSON LogMessage where
            ,"milliseconds" .= Text.pack (show ms) ]
       CiteprocWarning msg ->
            ["message" .= msg]
+      ATXHeadingInLHS lvl contents ->
+           ["level" .= lvl
+           ,"contents" .= contents]
 
-showPos :: SourcePos -> Text.Text
+showPos :: SourcePos -> Text
 showPos pos = Text.pack $ sn ++ "line " ++
      show (sourceLine pos) ++ " column " ++ show (sourceColumn pos)
   where sn = if sourceName pos == "source" || sourceName pos == ""
@@ -238,7 +243,7 @@ encodeLogMessages ms =
       keyOrder [ "type", "verbosity", "contents", "message", "path",
                  "source", "line", "column" ] } ms
 
-showLogMessage :: LogMessage -> Text.Text
+showLogMessage :: LogMessage -> Text
 showLogMessage msg =
   case msg of
        SkippedContent s pos ->
@@ -333,6 +338,13 @@ showLogMessage msg =
        FilterCompleted fp ms -> "Completed filter " <> Text.pack fp <>
           " in " <> Text.pack (show ms) <> " ms"
        CiteprocWarning ms -> "Citeproc: " <> ms
+       ATXHeadingInLHS lvl contents ->
+         "Rendering heading '" <> contents <> "' as a paragraph.\n" <>
+         "ATX headings cannot be used in literate Haskell, because " <>
+         "'#' is not\nallowed in column 1." <>
+         if lvl < 3
+            then " Consider using --markdown-headings=setext."
+            else ""
 
 messageVerbosity :: LogMessage -> Verbosity
 messageVerbosity msg =
@@ -378,3 +390,4 @@ messageVerbosity msg =
        RunningFilter{}               -> INFO
        FilterCompleted{}             -> INFO
        CiteprocWarning{}             -> WARNING
+       ATXHeadingInLHS{}             -> WARNING

src/Text/Pandoc/Options.hs

@@ -289,7 +289,7 @@ instance Default WriterOptions where
                       , writerTopLevelDivision = TopLevelDefault
                       , writerListings         = False
                       , writerHighlightStyle   = Just pygments
-                      , writerSetextHeaders    = True
+                      , writerSetextHeaders    = False
                       , writerEpubSubdirectory = "EPUB"
                       , writerEpubMetadata     = Nothing
                       , writerEpubFonts        = []

src/Text/Pandoc/Writers/Markdown.hs

@@ -514,6 +514,7 @@ blockToMarkdown' opts b@(RawBlock f str) = do
 blockToMarkdown' opts HorizontalRule =
   return $ blankline <> literal (T.replicate (writerColumns opts) "-") <> blankline
 blockToMarkdown' opts (Header level attr inlines) = do
+
   -- first, if we're putting references at the end of a section, we
   -- put them here.
   blkLevel <- asks envBlockLevel
@@ -543,8 +544,12 @@ blockToMarkdown' opts (Header level attr inlines) = do
                       isEnabled Ext_gutenberg opts
                       then capitalize inlines
                       else inlines
+
   let setext = writerSetextHeaders opts
-      hdr = nowrap $ case level of
+  when (not setext && isEnabled Ext_literate_haskell opts) $
+    report $ ATXHeadingInLHS level (render Nothing contents)
+
+  let hdr = nowrap $ case level of
             1 | variant == PlainText ->
                 if isEnabled Ext_gutenberg opts
                    then blanklines 3 <> contents <> blanklines 2

test/Tests/Old.hs

@@ -215,7 +215,8 @@ tests pandocPath =
     [ test' "reader" ["-f", "ipynb-raw_html-raw_tex+raw_attribute",
                       "-t", "native", "-s"]
       "ipynb/simple.ipynb" "ipynb/simple.out.native"
-    , test' "writer" ["-f", "native", "-t",
+    , test' "writer" ["-f", "native",
+                      "--markdown-headings=setext", "-t",
                       "ipynb-raw_html-raw_tex+raw_attribute", "-s"]
       "ipynb/simple.in.native" "ipynb/simple.ipynb"
     ]
@@ -241,7 +242,8 @@ lhsWriterTests pandocPath format
     ]
   where
     t n f = test pandocPath
-             n ["--wrap=preserve", "-r", "native", "-s", "-w", f]
+             n ["--wrap=preserve", "-r", "native", "-s",
+              "--markdown-headings=setext", "-w", f]
              "lhs-test.native" ("lhs-test" <.> f)
 
 lhsReaderTest :: FilePath -> String -> TestTree

test/Tests/Writers/Markdown.hs

@@ -12,7 +12,9 @@ import Text.Pandoc.Arbitrary ()
 import Text.Pandoc.Builder
 
 defopts :: WriterOptions
-defopts = def{ writerExtensions = pandocExtensions }
+defopts = def
+  { writerExtensions = pandocExtensions
+  , writerSetextHeaders = True }
 
 markdown :: (ToPandoc a) => a -> String
 markdown = unpack . purely (writeMarkdown defopts) . toPandoc

test/command/3674.md

@@ -2,7 +2,7 @@ Make sure we don't get duplicate reference links, even with
 `--reference-location=section`.
 
 ```
-% pandoc --reference-links -t markdown --reference-location=section --atx-headers
+% pandoc --reference-links -t markdown --reference-location=section
 # a
 
 ![](a)

test/command/3736.md

@@ -3,8 +3,7 @@
 <h2>hi
 there</h2>
 ^D
-hi there
+## hi there
---------
 ```
 
 ```
@@ -12,14 +11,12 @@ hi there
 <h2>hi <em>there
 again</em></h2>
 ^D
-hi *there again*
+## hi *there again*
-----------------
 ```
 
 ```
 % pandoc --wrap=preserve -f html -t markdown
 <h2>hi<br>there</h2>
 ^D
-hi there
+## hi there
---------
 ```

test/command/4038.md

@@ -1,5 +1,5 @@
 ```
-% pandoc -f gfm -t gfm --atx-headers
+% pandoc -f gfm -t gfm
 # ~~Header~~
 ^D
 # ~~Header~~

test/command/4164.md

@@ -2,11 +2,9 @@
 % pandoc -f opml -t markdown
 <?xml version="1.0"?> <opml version="1.0"> <head> <title> test </title> </head> <body> <outline text="test"> <outline text="try" _note="Here is inline html:&#xA;&#xA;&lt;div&gt; &#xA;&lt;balise&gt;&#xA;bla bla&#xA;&lt;/div&gt;"/> </outline> </body> </opml>
 ^D
-test
+# test
-====
 
-try
+## try
----
 
 Here is inline html:
 
@@ -22,11 +20,9 @@ Here is inline html:
 % pandoc -f opml-raw_html-native_divs -t markdown
 <?xml version="1.0"?> <opml version="1.0"> <head> <title> test </title> </head> <body> <outline text="test"> <outline text="try" _note="Here is inline html:&#xA;&#xA;&lt;div&gt; &#xA;&lt;balise&gt;&#xA;bla bla&#xA;&lt;/div&gt;"/> </outline> </body> </opml>
 ^D
-test
+# test
-====
 
-try
+## try
----
 
 Here is inline html:
 

test/command/5121.md

@@ -8,6 +8,5 @@
 <img src="./my-figure.jpg" width="500" alt="My caption" /><figcaption aria-hidden="true">My caption</figcaption>
 </figure>
 
-Header 2
+## Header 2
---------
 ```

test/command/6723.md

@@ -20,8 +20,7 @@ Blah [@doe].
 ^D
 Blah.[^1]
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-doe .csl-entry}

test/command/6837.md

@@ -0,0 +1,29 @@
+```
+% pandoc -t markdown --markdown-headings=setext
+## Hi
+
+### Ok
+^D
+Hi
+--
+
+### Ok
+```
+
+```
+% pandoc -t markdown+lhs
+# Hi
+^D
+[WARNING] Rendering heading 'Hi' as a paragraph.
+  ATX headings cannot be used in literate Haskell, because '#' is not
+  allowed in column 1. Consider using --markdown-headings=setext.
+Hi
+```
+
+```
+% pandoc -t markdown --markdown-headings=atx
+Hi
+--
+^D
+## Hi
+```

test/command/pandoc-citeproc-119.md

@@ -12,8 +12,7 @@ References {#references .unnumbered}
 ^D
 Averroes (1982); Averroes (1892); Averroes (1869)
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent line-spacing="2"}
 ::: {#ref-averroes/hercz .csl-entry}

test/command/pandoc-citeproc-14.md

@@ -54,8 +54,7 @@ References {#references .unnumbered}
 Foo (Pelikan 1971b, 1:12). Bar (Pelikan 1971c, 1:12). Baz (Pelikan
 1971a, 12).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-CTv1c2 .csl-entry}

test/command/pandoc-citeproc-152.md

@@ -43,13 +43,11 @@ I have two citations [@Feminism2013gf; @Feminism2011ces].
 References
 ==========
 ^D
-Test
+# Test
-====
 
 I have two citations ("Communities," 2011; "Geek Feminism," 2013).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent line-spacing="2"}
 ::: {#ref-Feminism2011ces .csl-entry}

test/command/pandoc-citeproc-160.md

@@ -26,13 +26,11 @@ Expected
 >
 > \[Jane11\] Jane Doe. A book. 2011.
 ^D
-No citation-label
+## No citation-label
------------------
 
 Foo \[Jane11\].
 
-Expected
+## Expected
---------
 
 > Foo \[Jane11\].
 >

test/command/pandoc-citeproc-175.md

@@ -27,13 +27,11 @@ Expected
 
 > Doe, Jane. 2011. "A Title." *A Magazine*, January--February.
 ^D
-Missing en-dash between months
+## Missing en-dash between months
-------------------------------
 
 Foo (Doe 2011).
 
-Expected
+## Expected
---------
 
 > Doe, Jane. 2011. "A Title." *A Magazine*, January--February.
 

test/command/pandoc-citeproc-213.md

@@ -23,8 +23,7 @@ References {#references .unnumbered}
 ^D
 Foo (Doe 1999).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-doe1 .csl-entry}

test/command/pandoc-citeproc-25.md

@@ -20,8 +20,7 @@ References {#references .unnumbered}
 ^D
 Foo (Author 1998).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-item1 .csl-entry}

test/command/pandoc-citeproc-27.md

@@ -25,8 +25,7 @@ Minimal example
 
 Here is some text that needs a citation [@AuthorOne2014].
 ^D
-Minimal example
+# Minimal example
-===============
 
 Here is some text that needs a citation (*1*).
 

test/command/pandoc-citeproc-371.md

@@ -26,8 +26,7 @@ References {#references .unnumbered}
 ^D
 Foo (Doe 2018, in press).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-item2 .csl-entry}

test/command/pandoc-citeproc-416.md

@@ -42,8 +42,7 @@ references:
 ^D
 Blah blah (Doe 2010, 2007, 2008).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-item2 .csl-entry}

test/command/pandoc-citeproc-47.md

@@ -90,8 +90,7 @@ coauthors' last names (regardless of how many coauthors there are)." and
 chronological order is maintained, regardless of the added abbreviation.
 \[ed., trans., comp., or whatever\]"
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-doe .csl-entry}

test/command/pandoc-citeproc-57.md

@@ -25,8 +25,7 @@ References
 ^D
 (Faraday, forthcoming)
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-Faraday-forthcoming .csl-entry}

test/command/pandoc-citeproc-58.md

@@ -22,8 +22,7 @@ References
 In this item, the title replaces the (unknown) author (see 14.79)
 (*Stanze in lode della donna brutta* 1547, 12).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-stanze .csl-entry}

test/command/pandoc-citeproc-61.md

@@ -41,8 +41,7 @@ Foo [@doe, CL, 89]
 References
 ==========
 ^D
-Text
+# Text
-====
 
 Foo[^1]
 
@@ -54,8 +53,7 @@ Foo[^4]
 
 Foo[^5]
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-doe .csl-entry}

test/command/pandoc-citeproc-82.md

@@ -24,8 +24,7 @@ Some text.[^1]
 
 [^1]: Comment regarding text, supported by citation [@OCLC_i1099].
 ^D
-Title
+# Title
-=====
 
 Some text.[^1]
 

test/command/pandoc-citeproc-87.md

@@ -120,8 +120,7 @@ Doe (2006e) -- article-newspaper
 
 Doe (2006b) -- article-newspaper YM
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-item2a .csl-entry}

test/command/pandoc-citeproc-chicago-author-date.md

@@ -48,8 +48,7 @@ References {#references .unnumbered}
     locator [-@item2 p. 44].
 ^D
 [WARNING] Citeproc: citation nonexistent not found
-Pandoc with citeproc-hs
+# Pandoc with citeproc-hs
-=======================
 
 ([**nonexistent?**](#ref-nonexistent))
 
@@ -82,8 +81,7 @@ Now some modifiers.[^3]
 
 With some markup (*see* [Doe 2005, 32](#ref-item1)).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-item1 .csl-entry}

test/command/pandoc-citeproc-chicago-fullnote-bibliography.md

@@ -49,8 +49,7 @@ References {#references .unnumbered}
     [-@item1], and now Doe with a locator [-@item2 p. 44].
 ^D
 [WARNING] Citeproc: citation nonexistent not found
-Pandoc with citeproc-hs
+# Pandoc with citeproc-hs
-=======================
 
 [^1]
 
@@ -80,8 +79,7 @@ Now some modifiers.[^13]
 
 With some markup.[^14]
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body .hanging-indent}
 ::: {#ref-item2 .csl-entry}

test/command/pandoc-citeproc-ieee.md

@@ -49,8 +49,7 @@ References {#references .unnumbered}
     locator [-@item2 p. 44].
 ^D
 [WARNING] Citeproc: citation nonexistent not found
-Pandoc with citeproc-hs
+# Pandoc with citeproc-hs
-=======================
 
 [**nonexistent?**](#ref-nonexistent)
 
@@ -83,8 +82,7 @@ Now some modifiers.[^3]
 
 With some markup *see* [\[1, p. 32\]](#ref-item1).
 
-References {#references .unnumbered}
+# References {#references .unnumbered}
-==========
 
 ::: {#refs .references .csl-bib-body}
 ::: {#ref-item1 .csl-entry}

test/command/toc.md

@@ -23,34 +23,25 @@
 -   [E](#e)
     -   [e](#e-1)
 
-A
+# A
-=
 
-b
+## b
--
 
-B
+# B
-=
 
-b
+## b
--
 
 ::: {.interior}
-C
+# C
-=
 
-cc
+## cc
---
 
-D
+# D
-=
 :::
 
 ::: {.blue}
-E
+# E
-=
 
-e
+## e
--
 :::
 ```

test/writer.markdown

@@ -11,11 +11,9 @@ markdown test suite.
 
 ------------------------------------------------------------------------------
 
-Headers
+# Headers
-=======
 
-Level 2 with an [embedded link](/url)
+## Level 2 with an [embedded link](/url)
--------------------------------------
 
 ### Level 3 with *emphasis*
 
@@ -23,25 +21,21 @@ Level 2 with an [embedded link](/url)
 
 ##### Level 5
 
-Level 1
+# Level 1
-=======
 
-Level 2 with *emphasis*
+## Level 2 with *emphasis*
------------------------
 
 ### Level 3
 
 with no blank line
 
-Level 2
+## Level 2
--------
 
 with no blank line
 
 ------------------------------------------------------------------------------
 
-Paragraphs
+# Paragraphs
-==========
 
 Here's a regular paragraph.
 
@@ -56,8 +50,7 @@ here.
 
 ------------------------------------------------------------------------------
 
-Block Quotes
+# Block Quotes
-============
 
 E-mail style:
 
@@ -86,8 +79,7 @@ And a following paragraph.
 
 ------------------------------------------------------------------------------
 
-Code Blocks
+# Code Blocks
-===========
 
 Code:
 
@@ -107,11 +99,9 @@ And:
 
 ------------------------------------------------------------------------------
 
-Lists
+# Lists
-=====
 
-Unordered
+## Unordered
----------
 
 Asterisks tight:
 
@@ -155,8 +145,7 @@ Minuses loose:
 
 -   Minus 3
 
-Ordered
+## Ordered
--------
 
 Tight:
 
@@ -196,8 +185,7 @@ Multiple paragraphs:
 
 3.  Item 3.
 
-Nested
+## Nested
-------
 
 -   Tab
     -   Tab
@@ -224,8 +212,7 @@ Same thing but with paragraphs:
 
 3.  Third
 
-Tabs and spaces
+## Tabs and spaces
----------------
 
 -   this is a list item indented with tabs
 
@@ -235,8 +222,7 @@ Tabs and spaces
 
     -   this is an example list item indented with spaces
 
-Fancy list markers
+## Fancy list markers
-------------------
 
 (2) begins with 2
 
@@ -270,8 +256,7 @@ B. Williams
 
 ------------------------------------------------------------------------------
 
-Definition Lists
+# Definition Lists
-================
 
 Tight using spaces:
 
@@ -364,8 +349,7 @@ orange
     1.  sublist
     2.  sublist
 
-HTML Blocks
+# HTML Blocks
-===========
 
 Simple block on one line:
 
@@ -525,8 +509,7 @@ Hr's:
 
 ------------------------------------------------------------------------------
 
-Inline Markup
+# Inline Markup
-=============
 
 This is *emphasized*, and so *is this*.
 
@@ -555,8 +538,7 @@ spaces: a\^b c\^d, a\~b c\~d.
 
 ------------------------------------------------------------------------------
 
-Smart quotes, ellipses, dashes
+# Smart quotes, ellipses, dashes
-==============================
 
 "Hello," said the spider. "'Shelob' is my name."
 
@@ -577,8 +559,7 @@ Ellipses...and...and....
 
 ------------------------------------------------------------------------------
 
-LaTeX
+# LaTeX
-=====
 
 -   `\cite[22-23]{smith.1899}`{=tex}
 -   $2+2=4$
@@ -610,8 +591,7 @@ Cat    & 1      \\ \hline
 
 ------------------------------------------------------------------------------
 
-Special Characters
+# Special Characters
-==================
 
 Here is some unicode:
 
@@ -665,11 +645,9 @@ Minus: -
 
 ------------------------------------------------------------------------------
 
-Links
+# Links
-=====
 
-Explicit
+## Explicit
---------
 
 Just a [URL](/url/).
 
@@ -689,8 +667,7 @@ Just a [URL](/url/).
 
 [Empty]().
 
-Reference
+## Reference
----------
 
 Foo [bar](/url/).
 
@@ -712,8 +689,7 @@ Foo [bar](/url/ "Title with "quotes" inside").
 
 Foo [biz](/url/ "Title with "quote" inside").
 
-With ampersands
+## With ampersands
----------------
 
 Here's a [link with an ampersand in the URL](http://example.com/?foo=1&bar=2).
 
@@ -724,8 +700,7 @@ Here's an [inline link](/script?foo=1&bar=2).
 
 Here's an [inline link in pointy braces](/script?foo=1&bar=2).
 
-Autolinks
+## Autolinks
----------
 
 With an ampersand: <http://example.com/?foo=1&bar=2>
 
@@ -743,8 +718,7 @@ Auto-links should not occur here: `<http://example.com/>`
 
 ------------------------------------------------------------------------------
 
-Images
+# Images
-======
 
 From "Voyage dans la Lune" by Georges Melies (1902):
 
@@ -754,8 +728,7 @@ Here is a movie ![movie](movie.jpg) icon.
 
 ------------------------------------------------------------------------------
 
-Footnotes
+# Footnotes
-=========
 
 Here is a footnote reference,[^1] and another.[^2] This should *not* be a
 footnote reference, because it contains a space.\[\^my note\] Here is an