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.

2 files changed, 25 insertions, 2 deletions

diff --git a/src/Text/Pandoc/App/CommandLineOptions.hs b/src/Text/Pandoc/App/CommandLineOptions.hs
index a82d8380e..661c6e06d 100644
--- a/src/Text/Pandoc/App/CommandLineOptions.hs
+++ b/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 }))
diff --git a/src/Text/Pandoc/App/Opt.hs b/src/Text/Pandoc/App/Opt.hs
index 64c61fb74..7e15b2cb0 100644
--- a/src/Text/Pandoc/App/Opt.hs
+++ b/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