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