[PATCH] Add option to export mixed Setext and ATX-style Markdown headlines

[Lee Thompson]

Greetings all,

This patch adds a new option `'mixed' to `org-md-headline-style' that
when enabled allows for exporting the first two headline levels in
Setext-style, and the rest in ATX-style. I like the mixed style for
certain situations, and I couldn't find a way to export in this manner.

I've added what I think is appropriate in the news file and the manual,
but this is my first time doing so, please let me know if this needs any
improvements/tweaks.

Thanks,
Lee

>From 6b281412c3d3522f445fd1d5b43aa1141ff0b531 Mon Sep 17 00:00:00 2001
From: Lee Thompson <lee.p.thomp@gmail.com>
Date: Sat, 11 May 2024 18:40:15 +0100
Subject: [PATCH] lisp/ox-md.el: Added mixed-style option to
 org-md-headline-style

* lisp/ox-md.el (org-md-headline-style): New setting `'mixed' allows
for mixing Setext and ATX-style headlines when exporting to Markdown.
* doc/org-manual.org (Header and sectioning structure): Documented
`mixed' headline style.
* etc/ORG-NEWS (New option added to custom setting
~org-md-headline-style~ to mix ATX and Setext style headlines):
Documented the new feature.

When exporting to Markdown, there was previously no obvious way of
mixing Setext-style and ATX-style headlines.  Via the
`org-md-headline-style' custom setting, headlines could be exported as
either all-Setext or all-ATX, but not as a mix.

With this change setting `org-md-headline-style' to `'mixed' will
export the first two headline levels as Setext-style Markdown
headlines and the rest as ATX-style.

TINYCHANGE
---
 doc/org-manual.org |  8 +++++---
 etc/ORG-NEWS       |  6 ++++++
 lisp/ox-md.el      | 15 ++++++++++-----
 3 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 3c60f3268f..e3a2c9b708 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -14788,9 +14788,11 @@ https://en.wikipedia.org/wiki/Markdown for more 
details.
 #+vindex: org-md-headline-style
 Based on ~org-md-headline-style~, Markdown export can generate
 headlines of both /atx/ and /setext/ types.  /setext/ limits headline
-levels to two whereas /atx/ limits headline levels to six.  Beyond
-these limits, the export backend converts headlines to lists.  To set
-a limit to a level before the absolute limit (see [[*Export Settings]]).
+levels to two whereas /atx/ limits headline levels to six.  /mixed/
+exports headline levels one and two in /setext/-style, and headline
+levels three through six as /atx/-style headlines.  Beyond these
+limits, the export backend converts headlines to lists.  To set a
+limit to a level before the absolute limit (see [[*Export Settings]]).
 
 ** OpenDocument Text Export
 :PROPERTIES:
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index 978882a7ad..0bff6e0608 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -1148,6 +1148,12 @@ blocks that do not specify any ~:formatter~ parameter. 
Its default
 value (the new function ~org-columns-dblock-write-default~) yields the
 previous (fixed) formatting behaviour.
 
+*** New option added to custom setting ~org-md-headline-style~ to mix ATX and 
Setext style headlines
+
+Setting ~org-md-headline-style~ to ~'mixed~ will export headline
+levels one and two as Setext style headlines, and headline levels
+three through six will be exported as ATX style headlines.
+
 ** New features
 *** =ob-lua=: Support all types and multiple values in results
 
diff --git a/lisp/ox-md.el b/lisp/ox-md.el
index 48a3e8387b..de4c572b29 100644
--- a/lisp/ox-md.el
+++ b/lisp/ox-md.el
@@ -47,11 +47,15 @@
 
 (defcustom org-md-headline-style 'atx
   "Style used to format headlines.
-This variable can be set to either `atx' or `setext'."
+This variable can be set to either `atx', `setext', or `mixed'.
+
+Mixed style uses Setext style markup for the first two headline levels
+and uses ATX style markup for the remaining four levels."
   :group 'org-export-md
   :type '(choice
          (const :tag "Use \"atx\" style" atx)
-         (const :tag "Use \"Setext\" style" setext)))
+         (const :tag "Use \"Setext\" style" setext)
+          (const :tag "Use \"mixed\" style" mixed)))
 
 
 ;;;; Footnotes
@@ -232,7 +236,7 @@ anchor tag for the section as a string.  TAGS are the tags 
set on
 the section."
   (let ((anchor-lines (and anchor (concat anchor "\n\n"))))
     ;; Use "Setext" style
-    (if (and (eq style 'setext) (< level 3))
+    (if (and (not (eq style 'atx)) (< level 3))
         (let* ((underline-char (if (= level 1) ?= ?-))
                (underline (concat (make-string (length title) underline-char)
                                  "\n")))
@@ -397,9 +401,10 @@ a communication channel."
       (cond
        ;; Cannot create a headline.  Fall-back to a list.
        ((or (org-export-low-level-p headline info)
-           (not (memq style '(atx setext)))
+           (not (memq style '(atx mixed setext)))
            (and (eq style 'atx) (> level 6))
-           (and (eq style 'setext) (> level 2)))
+           (and (eq style 'setext) (> level 2))
+           (and (eq style 'mixed) (> level 6)))
        (let ((bullet
               (if (not (org-export-numbered-headline-p headline info)) "-"
                 (concat (number-to-string
-- 
2.43.2