From b7f4afe86c36c36a751cb9dd31daa69051eec506 Mon Sep 17 00:00:00 2001 From: Rohit Patnaik Date: Tue, 23 Aug 2022 22:37:37 -0500 Subject: [PATCH] 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 0e8f22ced..57a57a6fe 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 d708e77f5..7dae03dc6 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 50db53910..481c76534 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