[Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Rohit Patnaik]

Hello,

I've been exporting several of my org-mode notes to markdown recently, and I've been running into an issue where I've had to manually adjust the level of the top level headings in my exported notes because the wiki system I'm importing the notes to reserves h1 (i.e. #) for page titles, using h2s (i.e. ##) for sections within the page itself.

I noticed that ox-html.el has a org-html-toplevel-hlevel variable, which allows the user to set the heading level of top-level headings within the exported content. Would there be any problems with implementing a similar variable (e.g. org-md-toplevel-hlevel) to allow the user to set the heading level of top level headings within exported markdown content?

It looks like it would be a small change, and I'd be happy to implement it myself, but I thought I'd run it by the list to see if there were any major issues that might arise from making this change.

Thanks,
Rohit Patnaik

Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Ihor Radchenko]

"Rohit Patnaik" <quanticle@quanticle.net> writes:

> Hello,
>
> I've been exporting several of my org-mode notes to markdown recently, and I've been running into an issue where I've had to manually adjust the level of the top level headings in my exported notes because the wiki system I'm importing the notes to reserves h1 (i.e. #) for page titles, using h2s (i.e. ##) for sections within the page itself.
>
> I noticed that ox-html.el has a org-html-toplevel-hlevel variable, which allows the user to set the heading level of top-level headings within the exported content. Would there be any problems with implementing a similar variable (e.g. org-md-toplevel-hlevel) to allow the user to set the heading level of top level headings within exported markdown content?

Sounds reasonable. I do not see any issue with this approach. Just be
careful to compute the level early before we decide the deeply-nested
headline style (org-md-headline-style).

> It looks like it would be a small change, and I'd be happy to implement it myself, but I thought I'd run it by the list to see if there were any major issues that might arise from making this change.

This contribution will be welcome.

-- 
Ihor Radchenko,
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: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Rohit Patnaik]

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

> This contribution will be welcome.

I've attached a patch which implements the change. I followed the pattern that
ox-html uses to the greatest extent possible. I tested it by exporting org-mode
files to markdown with the table of contents both enabled and disabled. I
didn't see any errors, and I was able to make the top level heading a level 2
(or even level 3) heading rather than level 1.

Thanks,
Rohit

[-- Attachment #2: 0001-Added-top-level-header-setting-for-md-export.patch --]
[-- Type: application/octet-stream, Size: 3072 bytes --]

From 185c43c2d7c15cd6df44c448d60bc88ea2a47402 Mon Sep 17 00:00:00 2001
From: Rohit Patnaik <quanticle@quanticle.net>
Date: Sun, 21 Aug 2022 00:20:03 -0500
Subject: [PATCH] Added top level header setting for md export

This commit adds a customization, org-md-toplevel-hlevel, which sets the
heading level of top-level headings in the exported markdown. This makes
markdown export behave more like HTML export, which reads
org-html-toplevel-hlevel to decide what the top level heading for HTML
export should be.
---
 lisp/ox-md.el | 23 +++++++++++++++++++----
 1 file changed, 19 insertions(+), 4 deletions(-)

diff --git a/lisp/ox-md.el b/lisp/ox-md.el
index 50db53910..7b9110890 100644
--- a/lisp/ox-md.el
+++ b/lisp/ox-md.el
@@ -71,6 +71,18 @@ The %s will be replaced by the footnote reference itself."
   :version "26.1"
   :package-version '(Org . "9.0"))
 
+(defcustom org-md-toplevel-hlevel 1
+  "The markdown heading level to use for level 1 headings in markdown export.
+If this is 1, the top level headings will be level 1 markdown headings. If this
+is 2, then top level headings will be level 2 markdown headings. By default 
+this is 1, so that org-mode headings correspond to the same level markdown
+headings. Incrementing this value may be helpful creating markdown for 
+inclusion in another document or application that reserves top-level headings
+for its own use."
+  :group 'org-export-md
+  :type 'string)
+
+
 \f
 ;;; Define Back-End
 
@@ -120,7 +132,8 @@ The %s will be replaced by the footnote reference itself."
   :options-alist
   '((:md-footnote-format nil nil org-md-footnote-format)
     (:md-footnotes-section nil nil org-md-footnotes-section)
-    (:md-headline-style nil nil org-md-headline-style)))
+    (:md-headline-style nil nil org-md-headline-style)
+    (:md-toplevel-hlevel nil nil org-md-toplevel-hlevel)))
 
 \f
 ;;; Filters
@@ -229,9 +242,10 @@ When optional argument SCOPE is non-nil, build a table of
 contents according to the specified element."
   (concat
    (unless scope
-     (let ((style (plist-get info :md-headline-style))
+     (let ((level (plist-get info :md-toplevel-hlevel))
+           (style (plist-get info :md-headline-style))
 	   (title (org-html--translate "Table of Contents" info)))
-       (org-md--headline-title style 1 title nil)))
+       (org-md--headline-title style level title nil)))
    (mapconcat
     (lambda (headline)
       (let* ((indentation
@@ -350,7 +364,8 @@ CONTENTS is nil.  INFO is a plist holding contextual information."
 CONTENTS is the headline contents.  INFO is a plist used as
 a communication channel."
   (unless (org-element-property :footnote-section-p headline)
-    (let* ((level (org-export-get-relative-level headline info))
+    (let* ((level (+ (org-export-get-relative-level headline info)
+                     (1- (plist-get info :md-toplevel-hlevel))))
 	   (title (org-export-data (org-element-property :title headline) info))
 	   (todo (and (plist-get info :with-todo-keywords)
 		      (let ((todo (org-element-property :todo-keyword
-- 
2.37.2.windows.2

Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Max Nikulin]

On 21/08/2022 18:07, Rohit Patnaik wrote:
> 
> I've attached a patch which implements the change.

Thank you for the patch.

> @@ -229,9 +242,10 @@ When optional argument SCOPE is non-nil, build a table of
>   contents according to the specified element."
>     (concat
>      (unless scope
> -     (let ((style (plist-get info :md-headline-style))
> +     (let ((level (plist-get info :md-toplevel-hlevel))
> +           (style (plist-get info :md-headline-style))

Since md backend is derived from html, is it necessary to define an 
option specific to markdown or the value defined for HTML may be reused? 
I am unsure which variant will be more convenient, so it is not more 
than an idea that may be easily discarded.

Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Ihor Radchenko]

"Rohit Patnaik" <quanticle@quanticle.net> writes:

>> This contribution will be welcome.
>
> I've attached a patch which implements the change. I followed the pattern that
> ox-html uses to the greatest extent possible. I tested it by exporting org-mode
> files to markdown with the table of contents both enabled and disabled. I
> didn't see any errors, and I was able to make the top level heading a level 2
> (or even level 3) heading rather than level 1.

Thanks for your contribution!
Please also add the NEWS entry and an item to "14.1.5 Options for the
exporters" section of the manual.

> Subject: [PATCH] Added top level header setting for md export
>
> This commit adds a customization, org-md-toplevel-hlevel, which sets the
> heading level of top-level headings in the exported markdown. This makes
> markdown export behave more like HTML export, which reads
> org-html-toplevel-hlevel to decide what the top level heading for HTML
> export should be.

Please follow the changelog style as described in
https://orgmode.org/worg/org-contribute.html#commit-messages

> +(defcustom org-md-toplevel-hlevel 1
> +  "The markdown heading level to use for level 1 headings in markdown export.
> +If this is 1, the top level headings will be level 1 markdown headings. If this
> +is 2, then top level headings will be level 2 markdown headings. By default 
> +this is 1, so that org-mode headings correspond to the same level markdown
> +headings. Incrementing this value may be helpful creating markdown for 
> +inclusion in another document or application that reserves top-level headings
> +for its own use."
> +  :group 'org-export-md
> +  :type 'string)

Please follow the recommended documentation style: double space between
sentences, 80 chars fill.
See "D.6 Tips for Documentation Strings" section of Elisp manual.

-- 
Ihor Radchenko,
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: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Max Nikulin]

On 21/08/2022 22:11, Rohit Patnaik wrote:
>> Since md backend is derived from html, is it necessary to define an
>> option specific to markdown or the value defined for HTML may be reused?
>> I am unsure which variant will be more convenient, so it is not more
>> than an idea that may be easily discarded.
> 
> I considered reusing the value from the HTML exporter, but I rejected it,
> because the org-html-toplevel-hlevel defaults to 2. Reusing it would alter the
> existing default behavior for markdown exports, which I thought was undesirable.

Thank you for clarification. I forgot that MarkDown has metadata block, 
while for HTML document title is the only option is <h1>. Of course, 
changing default is not an option and org-md-toplevel-hlevel is better.

Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Ihor Radchenko]

"Rohit Patnaik" <quanticle@quanticle.net> writes:

> I've added the entry in the NEWS file, added the entry for the new
> variable to section 14.1.5 of the manual, updated the docstring to
> have double space periods, and updated the commit message to follow
> the changelog style described on
> https://orgmode.org/worg/org-contribute.html#comment-messages.

Applied onto main via b7f4afe86 with amendments.
https://git.savannah.gnu.org/cgit/emacs/org-mode.git/commit/?id=b7f4afe86c36c36a751cb9dd31daa69051eec506

I have modified the commit message adding " " between sentences and
adding "." after sentences. Also, I added TINYCHANGE cookie as you do
not appear to have a copyright assignment.

Finally, I rewrote the variable docstring in order to make it more clear
(hopefully). I also refilled the docstring to 80 chars width.

Thanks for your contribution!

Best,
Ihor

Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export

[Rohit Patnaik]

Thanks so much for making those changes and getting it merged.

-- Rohit