Re: [O] [PATCH] Add TITLE export to ox-md
Hi, > The point of "md" export back-end is not to provide the same features as > full-fledged ones like "latex" or "html". I wrote it to take care of the > boring stuff of markdown syntax. Anyone willing to write a back-end with > a different Markdown flavour just needs to concentrate of the > differences between the original syntax. Ah, this makes a lot more sense now. I think that this patch is better suited towards more specific md backends (like ox-hugo or ox-gfm), so they can implement title in the way that supports their import the best. Adding this probably would get in the way of better title exports for the respective org exporter derivations. > AFAIC, I think ... or even ... > ..., as you suggested, are better choices. I do agree (from creating a vanilla markdown exporter standpoint), but I dislike it purely because the github markdown renderer doesn't display inline html that well (even though that's per standard). It ranges from being displayed as a H1 header to being displayed as normal (non-heading) text, depending on the way it's done. In summary, I think I'll try to get this into ox-gfm (and other org md exporters I can find) instead of ox-md. I think ox-hugo supports titles already though. Thanks again for taking a look at this! -Jay
Re: [O] [PATCH] Add TITLE export to ox-md
Hello, Jay Kamatwrites: > I agree that vanilla markdown does not support title, but if ox-md does not > support any form of title, then there is disparity between the output of other > org exports and the markdown exporter. I would like to solve that disparity if > possible. The point of "md" export back-end is not to provide the same features as full-fledged ones like "latex" or "html". I wrote it to take care of the boring stuff of markdown syntax. Anyone willing to write a back-end with a different Markdown flavour just needs to concentrate of the differences between the original syntax. IOW, discrepancy here is not a concern. > From the markdown that I've worked with, this isn't the case. The > original markdown tool (https://daringfireball.net/projects/markdown/) > dosen't seem to output filename titles in it's export, so I wouldn't > think it's part of the vanilla standard. I don't think either. >> Maybe we eventually end up with 3 options (something like below): >> >> - org-md-title-as-h1 >> - org-md-subtitle-as-h2 >> - org-md-heading-offset > > that's probably the best idea I've heard so far, since I would imagine most > people would either not want to have two H1 headings right after each other, > or > not want to have their headings shifted. Having such options would allow > people > to pick the scenario they want (shifting headings under the title, including > the > title but no offset, or not including the title at all). I don't think this is a good idea, because it makes "ox-md.el" less neutral. That could get in the way of other back-ends. AFAIC, I think ... or even ... ..., as you suggested, are better choices. Regards, -- Nicolas Goaziou
Re: [O] [PATCH] Add TITLE export to ox-md
> I'm not so sure about it. Vanilla Markdown does not support title. > Neither does "ox-md.el" I agree that vanilla markdown does not support title, but if ox-md does not support any form of title, then there is disparity between the output of other org exports and the markdown exporter. I would like to solve that disparity if possible. > Correct, vanilla Markdown does not support title. The file name is the title. I'm not entirely sure about that (file name being the title). Unfortunately markdown is very fragmented, so it's hard to tell what the 'standard' is. From the markdown that I've worked with, this isn't the case. The original markdown tool (https://daringfireball.net/projects/markdown/) dosen't seem to output filename titles in it's export, so I wouldn't think it's part of the vanilla standard. > But then you would need to shift all headlines 1 or 2 levels down. > `setext' style becomes unusable because there is no room left for other > headlines. Is there a reason we need to move all the other header under the title header? I was thinking of leaving the rest of the headlines as they are. So: #+TITLE: My Title * One ** Two Would export to # My Title # One ## Two It's a little bit ugly to have two h1 headings right next to each other, though. Another option is to take advantage of html features of markdown to format the title in a way that does not alter the headings (similar to how the TOC is exported now). For example, we could add My Title to the start of the markdown, but that seems to break the github markdown renderer. Does anyone who knows more html have any ideas here (besides adding h1 headings in html)? I don't like the idea of shifting headlines down a level to accommodate the title since people would then be unable to create new H1 headings in markdown files with a title. > Maybe we eventually end up with 3 options (something like below): > > - org-md-title-as-h1 > - org-md-subtitle-as-h2 > - org-md-heading-offset that's probably the best idea I've heard so far, since I would imagine most people would either not want to have two H1 headings right after each other, or not want to have their headings shifted. Having such options would allow people to pick the scenario they want (shifting headings under the title, including the title but no offset, or not including the title at all). Does creating these options (defaulting to nil) sound like a good plan to move forward on? Other ideas and feedback would be appreciated, (since this is a tricky situation, standards wise). -Jay PS: ox-hugo looks very nice, and I look forward to trying it out! :)
Re: [O] [PATCH] Add TITLE export to ox-md
On Thu, Aug 24, 2017, 5:31 AM Nicolas Goaziouwrote: > > I'm not so sure about it. Vanilla Markdown does not support title. > Neither does "ox-md.el" > Correct, vanilla Markdown does not support title. The file name is the title. For example, the file names of the Wiki pages on GitHub are rendered as titles (that is again not using 100% vanilla Markdown, but that's a good example specific to this question about titles). Is there any consensus about how title are handled in _vanilla_ syntax? > > > -(defun org-md-template (contents _info) > > +(defun org-md-template (contents info) > >"Return complete document string after Markdown conversion. > > CONTENTS is the transcoded contents string. INFO is a plist used > > as a communication channel." > > - contents) > > + (concat > > +;; Generate title and subtitle, if possible > > +(let ((title (and (plist-get info :with-title) > > +(plist-get info :title))) > > +(subtitle (plist-get info :subtitle)) > > +(style (plist-get info :md-headline-style))) > > + (when title > > + (concat > > + (org-md--headline-title style > > + 1 (org-export-data title info)) > > + (when subtitle > > + (org-md--headline-title style > > + 2 (org-export-data subtitle info)) > > +contents)) > > But then you would need to shift all headlines 1 or 2 levels down. > `setext' style becomes unusable because there is no room left for other > headlines. I will soon submit ox-hugo for review for submission to Org. That is an enhanced Makrdown exporter backend, that also handles the post front matter generation for the Hugo static site generator. In there, I have added an option for the user to set an offset for the headings in a post. By default an Org heading with 1 star becomes level-1 heading in Markdown. For ox-hugo, I have set the default to an offset of 1. So the 1-star Org headings will now become level-2 headings in Markdown. Here's a little snippet that implements that: (let ((level-mark (make-string (+ loffset level) ?#))) (concat "\n" level-mark " " todo title " " anchor "\n\n")) (Full code: https://github.com/kaushalmodi/ox-hugo/blob/master/ox-hugo.el) While that doesn't translate title and subtitle to level 1 and level 2 Markdown headings, it at least helps keep the font sizes of title and level-1 Markdown headings different. I would suggest making the title/subtitle to Markdown headings optional at best. Because most HTML renderers will render the file name as title. So will end up with duplicate titles: the one rendered from file name and another from the level-1 Markdown heading based on the above quoted org-md-template snippet. @Jay Would this offset option help in ox-md? Maybe we eventually end up with 3 options (something like below): - org-md-title-as-h1 - org-md-subtitle-as-h2 - org-md-heading-offset WDYT? (Side question: Would it be preferred to create a scratch branch on Org for reviewing ox-hugo? Or would the GitHub repo mentioned above be fine?) -- Kaushal Modi
Re: [O] [PATCH] Add TITLE export to ox-md
Hello, Jay Kamatwrites: > The markdown editor should support TITLE I'm not so sure about it. Vanilla Markdown does not support title. Neither does "ox-md.el" Is there any consensus about how title are handled in _vanilla_ syntax? > -(defun org-md-template (contents _info) > +(defun org-md-template (contents info) >"Return complete document string after Markdown conversion. > CONTENTS is the transcoded contents string. INFO is a plist used > as a communication channel." > - contents) > + (concat > +;; Generate title and subtitle, if possible > +(let ((title (and (plist-get info :with-title) > +(plist-get info :title))) > +(subtitle (plist-get info :subtitle)) > +(style (plist-get info :md-headline-style))) > + (when title > + (concat > + (org-md--headline-title style > + 1 (org-export-data title info)) > + (when subtitle > + (org-md--headline-title style > + 2 (org-export-data subtitle info)) > +contents)) But then you would need to shift all headlines 1 or 2 levels down. `setext' style becomes unusable because there is no room left for other headlines. Regards, -- Nicolas Goaziou
[O] [PATCH] Add TITLE export to ox-md
Hi! Currently, the markdown org exporter does not export titles. For example, the following org file: #+TITLE: My Title #+SUBTITLE: My Subtitle #+OPTIONS: toc:nil exports to an empty file. This patch adds title support to ox-md. Currently it exports them as markdown headers. For example, the above org file will export to: # My Title ## My Subtitle Of course, the title can be suppressed by adding #+OPTIONS: title:nil. The style used for the title export can be configured using the already existing org-md-headline-style variable. The markdown editor should support TITLE, but I'm not sure if this is the 'correct' way to support it. It seems like the simplest way for now. If people want it, I could add a new option to add different title export formats. There is an existing bug report and discussion at this issue tracker: https://github.com/larstvei/ox-gfm/issues/21. >From that issue, YAML front-matter is an option for title export, but I would like to stay away from that (at least by default) since that dosen't seem to be a feature in default markdown. Feedback, suggestions, and feature requests are very much appreciated! -Jay PS: Apologies if any part of this email is broken, I'm attempting to switch to gnus. >From fe45823c8b6da4ecae3347de4859127add03e253 Mon Sep 17 00:00:00 2001 From: Jay KamatDate: Sun, 20 Aug 2017 19:01:29 -0400 Subject: [PATCH] ox-md.el: Add TITLE export to markdown export * lisp/ox-md.el (org-md-template): Add title export to md template. Title will be exported as level 1 and 2 headers, as determined by org-md-headline-style See https://github.com/larstvei/ox-gfm/issues/21 for an external bug report --- lisp/ox-md.el | 18 +++--- 1 file changed, 15 insertions(+), 3 deletions(-) diff --git a/lisp/ox-md.el b/lisp/ox-md.el index ac94ba648..a552063e8 100644 --- a/lisp/ox-md.el +++ b/lisp/ox-md.el @@ -649,14 +649,26 @@ holding export options." ;; Footnotes section. (org-md--footnote-section info))) -(defun org-md-template (contents _info) +(defun org-md-template (contents info) "Return complete document string after Markdown conversion. CONTENTS is the transcoded contents string. INFO is a plist used as a communication channel." - contents) + (concat +;; Generate title and subtitle, if possible +(let ((title (and (plist-get info :with-title) + (plist-get info :title))) + (subtitle (plist-get info :subtitle)) + (style (plist-get info :md-headline-style))) + (when title + (concat + (org-md--headline-title style + 1 (org-export-data title info)) + (when subtitle + (org-md--headline-title style + 2 (org-export-data subtitle info)) +contents)) - ;;; Interactive function ;;;###autoload -- 2.11.0