[media-types] Re: +md as a text/markdown suffix

You mean:

markdown / <okf / skills / ... etc> + <common mark / github flavored / git
lab flavored / multimarkdown / pandoc markdown / markdown extra> ?

I don't love it : )

I think those flavors are all best represented with profile parameters or
separate subtypes.

https://datatracker.ietf.org/doc/html/rfc7764
https://datatracker.ietf.org/doc/rfc7763
https://www.iana.org/assignments/markdown-variants

https://github.com/search?q=text%2Fmarkdown%3B+variant&type=code

The real problem is where we need interoperability.
If the interoperability is only important in the yaml front matter, then
the rest is just text that "who cares how it looks, the agent will figure
it out."

Then I would suggest that if suffixes have a role to play, it is ensuring
the front matter is parsed consistently.

How bad of an idea is it to add more parameters later?

text/markdown; charset=UTF-8; variant=GFM; purpose=agent-skill (new
registry!)

Maybe markdown / PURPOSE + yaml-front

This would assume you can split the front matter consistently across all
variants... is that a known fact?

Some design requirements/suggestions to consider:

- preserve the parameter space for the registration of the subtype (avoid
starting with parameters)
- use a suffix when there is at least part of the media type that can be
consistently understood, without understanding all of it (not clear if that
is the case for yaml front matter)
- what happens when a new variant is added to IANA? Does it imply automatic
support in the "skill"?

At this point, the idea of a structured syntax suffix for (+md) seems bad
to me, unless it's explicitly related to the variants as "any now and any
future."
Then you could have the subtype carry the YAML-related requirements and
parameters.
If you want the subtype to carry everything needed for interop in both
markdown and yaml... I would not call it "+md"

As I understand it, YAML front matter is not supported in all variants.
Some variants support YAML front matter natively, while others have
platform-specific behavior.

As I chatted with an AI about this:

Many users assume front matter is standard Markdown because it is heavily
utilized in tools like Obsidian, Astro, and Jekyll. However, in these
environments, the Markdown parser itself isn't handling the YAML. Instead,
a pre-processor pipeline slices off the YAML metadata before sending the
rest of the text to a standard CommonMark or GFM engine.

I think it's a valid use of a suffix to indicate that you can strip YAML
off... the problem is you don't know what you have left behind... without
looking at the subtype?
If the subtype refuses to pin the markdown flavor, I don't see how this
will have any interoperability.

I think preserving human readability is a requirement here.



On Sat, Aug 22, 2026 at 1:56 AM Mark Nottingham <[email protected]> wrote:

> Just thinking out loud: what about a 'markdown' top level type, with
> +suffixes for the different flavours?
>
>
> > On 21 Aug 2026, at 2:30 pm, Orie <[email protected]> wrote:
> >
> > I thought a bit more about this, and I think it might be a bad idea to
> use +md where we could be using a parameter.
> > I am also suspicious of the "text" type vs "application" type given the
> yaml front matter.
> >
> > I would love to see something helpful done for this problem space
> though, it seems like an increasingly important building block.
> >
> > Setting aside what I know about how we got the current media types, I
> would probably attack the problem like this:
> >
> > application/agent-context;profile=okf / obsidian / ... skills / other
> stuff
> >
> > This feels like possibly creating a big tent that nobody asked for, so
> you might consider:
> >
> > application/okf (or whatever other flavors)
> >
> > I have a feeling that using +md would lead to many subtypes needed to
> carry semantics, instead of carrying application configuration types, which
> I think is what all these things are.
> >
> > That being said, if we think there will be a big enough pile of these
> sorts of things where consistent processing of the suffix for rendering is
> helpful, even if the specific structure in the yaml or markdown is not
> actually checked in the context of the configuration type, it might be
> worth it.
> >
> > I would be extremely cautious about the cases where the markdown or yaml
> failed to parse / display for +md ... Squashing 2 media types together
> creates many error cases, and with one of those media types supporting many
> flavors, that risk multiplies.
> >
> > Potentially triggering, but given how important markdown is for this
> domain (AI Agent Context Engineering), maybe it's best we start considering
> the benefits of picking a winner.
> >
> > If we did register a +md or +ctx (context?), I would want to see a
> regular media type defined alongside it that reduces the risks related to
> supported syntax and features and change control.
> >
> >
> >
> > On Fri, Aug 21, 2026 at 2:19 AM Paul Libbrecht <paul=
> [email protected]> wrote:
> > Hello list,
> >
> > I think that what made the success of the many markdown flavours is
> their ability to “degrade gracefully” in the eyes of end-users by showing a
> text that seems human-readable. The YAML additions aimed at the same.
> >
> > Maybe that can be enough for a description of the encoding? At the end
> it seems much like plain-text but with a little chance of some automatic
> processing, which is probably expected to never fail when in a display
> process, even if the user needs more cognitive resources to interpret it.
> >
> > Paul
> >
> >
> > On 21 Aug 2026, at 2:37, Mark Nottingham wrote:
> >
> > > Registering markdown as a suffix seems to invert that -- it says
> "here's a family of formats that share semantics, but they're spelled
> differently on the wire." That's assuming that you want to accommodate all
> of the various flavours and complications of modern markdown, and not
> choose a winner.
> >
> >
> > On 21 Aug 2026, at 0:04, Orie wrote:
> >
> > > Aren't there lots of flavors of markdown?
> >
> > _______________________________________________
> > media-types mailing list -- [email protected]
> > To unsubscribe send an email to [email protected]
> > _______________________________________________
> > media-types mailing list -- [email protected]
> > To unsubscribe send an email to [email protected]
>
> --
> Mark Nottingham   https://mnot.net/
>
>

_______________________________________________
media-types mailing list -- [email protected]
To unsubscribe send an email to [email protected]