* [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export @ 2022-08-19 20:20 Rohit Patnaik 2022-08-20 7:49 ` Ihor Radchenko 0 siblings, 1 reply; 8+ messages in thread From: Rohit Patnaik @ 2022-08-19 20:20 UTC (permalink / raw) To: emacs-orgmode 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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export 2022-08-19 20:20 [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 @ 2022-08-20 7:49 ` Ihor Radchenko 2022-08-21 11:07 ` Rohit Patnaik 0 siblings, 1 reply; 8+ messages in thread From: Ihor Radchenko @ 2022-08-20 7:49 UTC (permalink / raw) To: Rohit Patnaik; +Cc: emacs-orgmode "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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export 2022-08-20 7:49 ` Ihor Radchenko @ 2022-08-21 11:07 ` Rohit Patnaik 2022-08-21 14:26 ` Max Nikulin 2022-08-22 2:59 ` Ihor Radchenko 0 siblings, 2 replies; 8+ messages in thread From: Rohit Patnaik @ 2022-08-21 11:07 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode [-- 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 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export 2022-08-21 11:07 ` Rohit Patnaik @ 2022-08-21 14:26 ` Max Nikulin [not found] ` <47b3902e-cc80-4317-a761-9301abd50b3c@www.fastmail.com> 2022-08-22 2:59 ` Ihor Radchenko 1 sibling, 1 reply; 8+ messages in thread From: Max Nikulin @ 2022-08-21 14:26 UTC (permalink / raw) To: emacs-orgmode 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
[parent not found: <47b3902e-cc80-4317-a761-9301abd50b3c@www.fastmail.com>]
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export [not found] ` <47b3902e-cc80-4317-a761-9301abd50b3c@www.fastmail.com> @ 2022-08-22 12:03 ` Max Nikulin 0 siblings, 0 replies; 8+ messages in thread From: Max Nikulin @ 2022-08-22 12:03 UTC (permalink / raw) To: emacs-orgmode 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. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export 2022-08-21 11:07 ` Rohit Patnaik 2022-08-21 14:26 ` Max Nikulin @ 2022-08-22 2:59 ` Ihor Radchenko [not found] ` <1335376b-0eeb-472c-8b8d-988eb0bdd04b@www.fastmail.com> 1 sibling, 1 reply; 8+ messages in thread From: Ihor Radchenko @ 2022-08-22 2:59 UTC (permalink / raw) To: Rohit Patnaik; +Cc: emacs-orgmode "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 ^ permalink raw reply [flat|nested] 8+ messages in thread
[parent not found: <1335376b-0eeb-472c-8b8d-988eb0bdd04b@www.fastmail.com>]
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export [not found] ` <1335376b-0eeb-472c-8b8d-988eb0bdd04b@www.fastmail.com> @ 2022-08-26 13:07 ` Ihor Radchenko 2022-08-26 15:34 ` Rohit Patnaik 0 siblings, 1 reply; 8+ messages in thread From: Ihor Radchenko @ 2022-08-26 13:07 UTC (permalink / raw) To: Rohit Patnaik; +Cc: emacs-orgmode "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 ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [Feature Request] Create an org-md-toplevel-hlevel variable to allow users to set the level of top level headings in markdown export 2022-08-26 13:07 ` Ihor Radchenko @ 2022-08-26 15:34 ` Rohit Patnaik 0 siblings, 0 replies; 8+ messages in thread From: Rohit Patnaik @ 2022-08-26 15:34 UTC (permalink / raw) To: Ihor Radchenko; +Cc: emacs-orgmode Thanks so much for making those changes and getting it merged. -- Rohit ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2022-08-26 16:17 UTC | newest]
Thread overview: 8+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-08-19 20:20 [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
2022-08-20 7:49 ` Ihor Radchenko
2022-08-21 11:07 ` Rohit Patnaik
2022-08-21 14:26 ` Max Nikulin
[not found] ` <47b3902e-cc80-4317-a761-9301abd50b3c@www.fastmail.com>
2022-08-22 12:03 ` Max Nikulin
2022-08-22 2:59 ` Ihor Radchenko
[not found] ` <1335376b-0eeb-472c-8b8d-988eb0bdd04b@www.fastmail.com>
2022-08-26 13:07 ` Ihor Radchenko
2022-08-26 15:34 ` Rohit Patnaik
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs/org-mode.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).