Define and use media types for Hugo's content formats

[bep]

This is defined/implemented in #12440 -- but I'll create an issue for visibility.

Type	Extensions
text/markdown	md, mdown, markdown
text/asciidoc	adoc, asciidoc, ad
text/pandoc	pandoc, pdc
text/x-rst	rst
text/org	org
text/html	html,htm

It will be possible to redefine these (add/edit/remove extensions).

[jmooring]

Will this have any effect on the markup front matter or the markup value in the .Page.RenderString options map? If we didn't care about backwards compatibility, I would vote to use the content type for both, e.g.,

{{ "some **bold** text" | .RenderString (dict "markup" "text/markdown") }}

+++
title = 'My page'
markup = 'text/x-asciidoc'
+++

[bep]

If we didn't care about backwards compatibility

... but we do ...

The common case is to resolve this from the file extension (e.g. md => text/markdown); in the current content format docs there are some odd outliers (asciidocext, goldmark -- which I guess comes from a time where we had multiple options for Markdown), but other than that it currently maps nicely with how we resolve media types elsewhere.

[jmooring]

If you want to render an asciidoc string any of these work:

{{ "foo" | .RenderString (dict "markup" "asciidocext") }}
{{ "foo" | .RenderString (dict "markup" "asciidoc") }}
{{ "foo" | .RenderString (dict "markup" "adoc") }}
{{ "foo" | .RenderString (dict "markup" "ad") }}

So I guess you can specify any of the associated extensions, but will that be true if users can add/remove extensions?

[bep]

So I guess you can specify any of the associated extensions, but will that be true if users can add/remove extensions?

If people want to shoot themselves in the foot, they can break constructs ala

{{ "foo" | .RenderString (dict "markup" "adoc") }}

By redefining the asciidoc media type.

My main goal moving this into the "media type" setup was to get away from the global hard coded setup (isMarkdown := ext == "md" || ext == ...). We can certainly always use the pre-defined values, but I'm not sure that I see the big problem. I suspect it could be useful to, say, add xhtml to the list. Maybe.

But we can certainly start documenting this to say that markup requires the media type -- but we still need to map file extensions to media types.

[jmooring]

There isn't a problem. I'm just trying to get this right:

Which I think is fine. And for the markup front matter field and RenderString option we instruct users to use the "identifier" as shown in the table above (despite the fact that other values work... keep it simple).

[bep]

Your media types doesn't match my table above.

[jmooring]

Corrected. Didn't catch the change.

[bep]

Thinking about this, if we made the media types look like:

Type	Extensions
text/markdown	md, mdown, markdown
text/asciidoc	adoc, asciidoc, ad
text/pandoc	pandoc, pdc
text/rst	rst
text/org	org
text/html	html,htm

Most of these does not have official MIME types, and you're supposed to prefix them with x-, but in this situation it makes it cleaner just drop that for all of these.

That way the identifier would be the MIME sub type, e.g.: asciidoc.

[jmooring]

Works for me.