[elpa] externals/org b7f4afe86c 1/2: lisp/ox-md.el: Add top level header setting

[ELPA Syncer]

branch: externals/org
commit b7f4afe86c36c36a751cb9dd31daa69051eec506
Author: Rohit Patnaik <quanticle@quanticle.net>
Commit: Ihor Radchenko <yantar92@gmail.com>

    lisp/ox-md.el: Add top level header setting
    
    * lisp/ox-md.el (defcustom org-md-toplevel-hlevel): Define the customizable
    variable that defines the top level heading to use when exporting to 
markdown.
    (org-export-define-derived-backend): Read the value of the new
    `org-md-toplevel-hlevel' variable into the `:options-alist' for this backend
    (org-md--build-toc): Use the newly defined top-level heading setting to 
control
    the heading level for the "Table of Contents" text.
    (org-md-headline): Use the newly defined top-level heading setting as an 
offset
    to the heading level calculated by `org-export-get-relative-level'.
    
    This patch adds a new setting: `org-md-toplevel-hlevel' that controls which
    Markdown heading level is used for top level headings.  This change makes
    markdown export more like HTML export, which has a 
`org-html-toplevel-hlevel'
    variable which does the same thing for HTML export.
    
    TINYCHANGE
---
 doc/org-manual.org |  1 +
 etc/ORG-NEWS       |  6 ++++++
 lisp/ox-md.el      | 26 ++++++++++++++++++++++----
 3 files changed, 29 insertions(+), 4 deletions(-)

diff --git a/doc/org-manual.org b/doc/org-manual.org
index 0e8f22ced3..57a57a6fe6 100644
--- a/doc/org-manual.org
+++ b/doc/org-manual.org
@@ -16405,6 +16405,7 @@ Settings]]), however, override everything.
 | ~:md-footnote-format~   | ~org-md-footnote-format~   |
 | ~:md-footnotes-section~ | ~org-md-footnotes-section~ |
 | ~:md-headline-style~    | ~org-md-headline-style~    |
+| ~:md-toplevel-hlevel~   | ~org-md-toplevel-hlevel~   |
 
 **** ODT specific properties
 :PROPERTIES:
diff --git a/etc/ORG-NEWS b/etc/ORG-NEWS
index d708e77f5b..7dae03dc66 100644
--- a/etc/ORG-NEWS
+++ b/etc/ORG-NEWS
@@ -282,6 +282,12 @@ file name.  For example:
 
 If a file does not have a title, the table will show the file name
 instead.
+*** New =org-md-toplevel-hlevel= variable for Markdown export
+
+The =org-md-toplevel-hlevel= customization variable sets the heading
+level used for top level headings, much like how
+=org-html-toplevel-hlevel= sets the heading level used for top level
+headings in HTML export.
 
 ** New options
 *** A new custom setting =org-hide-drawer-startup= to control initial folding 
state of drawers
diff --git a/lisp/ox-md.el b/lisp/ox-md.el
index 50db53910a..481c765343 100644
--- a/lisp/ox-md.el
+++ b/lisp/ox-md.el
@@ -71,6 +71,21 @@ The %s will be replaced by the footnote reference itself."
   :version "26.1"
   :package-version '(Org . "9.0"))
 
+(defcustom org-md-toplevel-hlevel 1
+  "Heading level to use for level 1 Org headings in markdown export.
+
+If this is 1, headline levels will be preserved on export.  If this is
+2, top level Org headings will be exported to level 2 markdown
+headings, level 2 Org headings will be exported to level 3 markdown
+headings, and so on.
+
+Incrementing this value may be helpful when creating markdown to be
+included into another document or application that reserves top-level
+headings for its own use."
+  :group 'org-export-md
+  :type 'string)
+
+
 
 ;;; Define Back-End
 
@@ -120,7 +135,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)))
 
 
 ;;; Filters
@@ -229,9 +245,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 +367,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