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

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

[Lee Thompson]

[-- Attachment #1: Type: text/plain, Size: 473 bytes --]

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

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch file --]
[-- Type: text/x-patch, Size: 4593 bytes --]

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

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

[Ihor Radchenko]

Lee Thompson <lee.p.thomp@gmail.com> writes:

> 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.

But isn't (setq org-md-headline-style 'setext) do exactly what you describe?

I just tried with
#+options: toc:nil
* 1
** 2
*** 3
**** 4

It exports to

One
===


Two
---

1.  Three

    1.  Four

AFAIK, headlines below level 2 simply cannot be exported with setext
style, so Org mode already falls back to atx in >2 levels.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

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

[Lee Thompson]

Hi Ihor,

> But isn't (setq org-md-headline-style 'setext) do exactly what you describe?
My apologies, I should have included an example. What I'm trying to
achieve is that instead of this: (set to setext)
> One
> ===
>
>
> Two
> ---
>
> 1.  Three
>
>     1.  Four

Or even something like this: (atx assuming #+options: h:4)

# One


## Two


### Three


#### Four


Setting `org-md-headline-style' to `'mixed' would produce the following:
(again assuming #+options: h:4)

One
===


Two
---


### Three


#### Four

> AFAIK, headlines below level 2 simply cannot be exported with setext
> style, so Org mode already falls back to atx in >2 levels.
Unless I'm doing something wrong or I've been hacking away with older
code I haven't observed this. It may be that I'm getting mixed up in
terminology and what you've demonstrated in your example is indeed
setext falling back to atx, but my understanding is that in your example
the first two headlines are in setext style and the third and
fourth-level headlines have been converted to Markdown lists.

What I am proposing is a style where setext-style underlined headlines
are generated for levels 1 and 2, atx-style repeated hash characters for
levels 3 to 6, and then converted to lists for deeper levels. To
demonstrate:

#+options: toc:nil h:6
* One

** Two
*** Three
**** Four
***** Five
****** Six
******* Seven
******** Eight

Exports to:

One
===


Two
---


### Three


#### Four


##### Five


###### Six

1.  Seven

    1.  Eight


I hope this explains more clearly what I'm trying to achieve, do let me
know if not.

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

[Ihor Radchenko]

Lee Thompson <lee.p.thomp@gmail.com> writes:

> ...
> I hope this explains more clearly what I'm trying to achieve, do let me
> know if not.

Yes.
Applied, onto main, with amendments.
I changed the commit message and news style to imperative and tweaked
one place in the code to not rely upon the existing set of the possible
options.

https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=1a7d7a5a5
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=fffb87174

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>