Org mode improvements (extend markdownify to support all markup formats)

[niklasfasching]

• document org front matter format
• introduce htmlify (Feature Request: Add an Org.toHTML function [go-org] #5589)

[bep]

We need to stop a minute and think a little about the name. I may have thought these "ify" function names was clever (I think we stole it from Jekyll), but I'm not so sure anymore. markdownify was obviously not fantastic.

I suggest we call the new one Markup.

That said, we also need to specify the block (paragraphs) vs inline behaviour of such func. There are miles of discussions about this elsewhere, so I will not go into details.

/cc @kaushalmodi @regisphilibert and the paragraph riders.

[kaushalmodi]

I agree that the "ify" names are getting old.

I suggest we call the new one Markup.

How about toHTML in Markdown, Org, .. namespaces?

Can we have something like:

{{ "**BatMan**" | Markdown.toHTML }}

{{ "*BatMan*" | Org.toHTML }}

I feel like above are readable as in plain English too.

[bep]

The current namespace is transform.Markdownify (I don't want 1 function namespaces) and I suggest we do transform.Markup. The name is pretty good, and another reason is that I plan to add .Page.Markup method which defaults to the renderer or the page itself. It would be good if they shared the same name (and we're not adding a bunch of new methods to the alrady big Page interface).

[kaushalmodi]

The current namespace is transform.Markdownify (I don't want 1 function namespaces)

OK, understood.

I suggest we do transform.Markup

I suggested toHTML so that it's clear that that function's outcome is HTML string. With just Markup, it's not clear..

• Are you marking up the input to the markup in the argument?
• Are you transforming the markup in the input to something else? If so, what?

So.. how about a middle ground.. transform.ToHTML?

Then you can have:

{{ "**BatMan**" | ToHTML "markdown"  }}

{{ "*BatMan*" | ToHTML "org" }}

another reason is that I plan to add .Page.Markup method

I think .Page.ToHTML would sound good and appropriate there too. What do you think?

[regisphilibert]

I'm sorry I don't have any suggestion here. But for me Markup in the global sense is not HTML only, it's an ensemble of factors determining the look of your page. CSS is part of the "Markup".

Originally these the little handwritten comments added next to the text to indicate the publisher how those element should be "styled" on once printed.

[kaushalmodi]

@regisphilibert As an aside.. that you mention:

Originally these the little handwritten comments added next to the text to indicate the publisher how those element should be "styled" on once printed.

https://shadycharacters.co.uk/ is an awesome read if you are interested in such topics related to publishing and special characters 😃

[niklasfasching]

I suggest we do transform.Markup

So.. how about a middle ground.. transform.ToHTML

I don't care either way but I'm unsure where to go from here.

[kaushalmodi]

Given that no one has a preference, but I do, @bep, does my proposal in #6043 (comment) sound good? 🙂

[bep]

Given that no one has a preference,

I have a preference, which is the more general term mentioned earlier.

• When I say .Markup (which is the page contextual variant of what we discuss here) I say: Render this using the page's rendering engine to the current output format.
• I understand that what we currently have renders to HTML only, I would be rather disappointed if the future did not bring ... more.

[bep]

@kaushalmodi @niklasfasching sorry, I have been slightly distracted lately. I think I will delay parts of this discussion to a later time. For this particular PR I will say that we cannot add another function with a different name but with almost identical functionality (you have no idea how much time just explaining the difference to people will add up to, even if we add fantastic docs).

So, also saying that in the future we need something to indicate block vs inline for this, I suggest that we:

1. Keep the name markdownify for now. We can create an alias for it once we know what that is.
2. Add an optional options map so I can do {{ "=hello=" | markdownify (dict "format" "org") }}

The above will map fairly nicely to the .Markdownify func, which then uses the page context to guess the above.

[bep]

Bump.

[niklasfasching]

Got distracted - I'll look into this on the weekend :)

[stale]

This issue has been automatically marked as stale because it has not had recent activity. The resources of the Hugo team are limited, and so we are asking for your help.
If this is a bug and you can still reproduce this error on the master branch, please reply with all of the information you have about it in order to keep the issue open.
If this is a feature request, and you feel that it is still relevant and valuable, please tell us why.
This issue will automatically be closed in the near future if no further activity occurs. Thank you for all your contributions.

[bep]

I will probably replace this PR now ...

I have thought about this, and I think .Page.RenderString (which renders a string to the current output format, will fall back to HTML for now) would be an OK name. It's a little bit mouthy, but I think it describes what it does well. It also pairs nicely with .Page.Render.

/cc @regisphilibert

[regisphilibert]

I'm a bit confused here as of the purpose of this .ToOutputFormat method. Its name evokes compatibility with multiple output. I understand it can take either markdown or org as input but I'm not sure I can figure what output, other than HTML, it could ever produce?

If I'm working on a JSON template file and I use .Page.ToOutputFormat, what does happen?

[bep]

@regisphilibert I changed my mind as I wrote it ... See my update. You are too fast.

[regisphilibert]

Yes .RenderString is great! And now I see we're talking about Rendering a string with shortcode, markdown etc... This will help greatly building pages with Front Matter Blocks! 🎉

[github-actions]

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.