* [PATCH] Add TITLE export to ox-md
@ 2017-08-24 3:32 Jay Kamat
2017-08-24 9:30 ` Nicolas Goaziou
0 siblings, 1 reply; 6+ messages in thread
From: Jay Kamat @ 2017-08-24 3:32 UTC (permalink / raw)
To: emacs-orgmode
[-- Attachment #1: Type: text/plain, Size: 1241 bytes --]
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.
[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-ox-md.el-Add-TITLE-export-to-markdown-export.patch --]
[-- Type: text/x-diff, Size: 1545 bytes --]
From fe45823c8b6da4ecae3347de4859127add03e253 Mon Sep 17 00:00:00 2001
From: Jay Kamat <jaygkamat@gmail.com>
Date: 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))
-\f
;;; Interactive function
;;;###autoload
--
2.11.0
^ permalink raw reply related [flat|nested] 6+ messages in thread
* Re: [PATCH] Add TITLE export to ox-md
2017-08-24 3:32 [PATCH] Add TITLE export to ox-md Jay Kamat
@ 2017-08-24 9:30 ` Nicolas Goaziou
2017-08-24 10:28 ` Kaushal Modi
0 siblings, 1 reply; 6+ messages in thread
From: Nicolas Goaziou @ 2017-08-24 9:30 UTC (permalink / raw)
To: Jay Kamat; +Cc: emacs-orgmode
Hello,
Jay Kamat <jaygkamat@gmail.com> writes:
> 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
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add TITLE export to ox-md
2017-08-24 9:30 ` Nicolas Goaziou
@ 2017-08-24 10:28 ` Kaushal Modi
2017-08-24 14:41 ` Jay Kamat
0 siblings, 1 reply; 6+ messages in thread
From: Kaushal Modi @ 2017-08-24 10:28 UTC (permalink / raw)
To: Nicolas Goaziou, Jay Kamat; +Cc: emacs-org list
[-- Attachment #1: Type: text/plain, Size: 3098 bytes --]
On Thu, Aug 24, 2017, 5:31 AM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:
>
> 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
[-- Attachment #2: Type: text/html, Size: 4362 bytes --]
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add TITLE export to ox-md
2017-08-24 10:28 ` Kaushal Modi
@ 2017-08-24 14:41 ` Jay Kamat
2017-08-26 8:11 ` Nicolas Goaziou
0 siblings, 1 reply; 6+ messages in thread
From: Jay Kamat @ 2017-08-24 14:41 UTC (permalink / raw)
To: Kaushal Modi; +Cc: emacs-org list, Nicolas Goaziou
> 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
<head>
<title>My Title</title>
</head>
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! :)
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add TITLE export to ox-md
2017-08-24 14:41 ` Jay Kamat
@ 2017-08-26 8:11 ` Nicolas Goaziou
2017-08-28 2:43 ` Jay Kamat
0 siblings, 1 reply; 6+ messages in thread
From: Nicolas Goaziou @ 2017-08-26 8:11 UTC (permalink / raw)
To: Jay Kamat; +Cc: emacs-org list, Kaushal Modi
Hello,
Jay Kamat <jaygkamat@gmail.com> writes:
> 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 <title>...</title> or even <header>...</header>
<main>...</main>, as you suggested, are better choices.
Regards,
--
Nicolas Goaziou
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH] Add TITLE export to ox-md
2017-08-26 8:11 ` Nicolas Goaziou
@ 2017-08-28 2:43 ` Jay Kamat
0 siblings, 0 replies; 6+ messages in thread
From: Jay Kamat @ 2017-08-28 2:43 UTC (permalink / raw)
To: Nicolas Goaziou; +Cc: emacs-org list, Kaushal Modi
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 <title>...</title> or even <header>...</header>
> <main>...</main>, 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
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2017-08-28 2:43 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-08-24 3:32 [PATCH] Add TITLE export to ox-md Jay Kamat
2017-08-24 9:30 ` Nicolas Goaziou
2017-08-24 10:28 ` Kaushal Modi
2017-08-24 14:41 ` Jay Kamat
2017-08-26 8:11 ` Nicolas Goaziou
2017-08-28 2:43 ` Jay Kamat
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).