[media-types] [IANA #1445779] text/vnd.gist.mx registration request

[Amanda Baber via RT <[e-mail]>]

Hi Darrel,

Sending a reminder for this message from May 22nd.

thanks,
Amanda

On Fri May 22 22:27:55 2026, amanda.baber wrote:
> Hi Darrel,
> 
> We have a response from Sachin:
> 
> ===
> 
> Thank you for sharing the detailed feedback. The reviewer is right
> about the signature block. JWS, EdDSA, DID keys — none of that is
> human-readable prose and it doesn't belong in the core spec. We will
> remove it entirely. The core spec will now only has natural language
> prose fields plus two plain SHA-256 hash scalars for source integrity
> and tamper detection. We should have caught this earlier and we
> concede to this point fully.
> 
> On the suggestion to just use text/markdown, we've heard this couple
> of times now from the reviewer and want to be direct about why it
> doesn't work. The text/markdown tells a receiver it has a markdown
> document. It says nothing about whether comprehension layers are
> present or what produced them. Without a registered type, there's no
> stable identifier for third-party tools to implement .mx support
> against, and no way for any tool to know this file is anything other
> than plain markdown without parsing it first. That defeats the whole
> purpose of having a media type. text/calendar doesn't exist because
> machines can't read iCal, it exists so machines can identify it and
> present it correctly to humans. Same logic applies here.
> 
> On the vendor tree precedent concern, the RFC 6838 section 3.2 defines
> the vendor tree specifically for media types associated with
> commercially available products. That is exactly what this is. There
> are already dozens of vnd. registrations extending existing text
> formats. We're not doing anything unusual.
> 
> On text/calendar and text/vcard, we accept that the email inline
> rendering argument is weak, but those registrations have not been
> moved to application/ in 28 years and are still listed as text/ in the
> IANA registry. Our updated spec contains more natural language content
> than vCard and is less structurally complex than iCalendar. The
> standing precedent supports our registration.
> 
> The updated spec will be uploaded at https://github.com/gistmx/spec
> later today. We're happy to get on a call with the reviewer if that
> would help move this forward.
> 
> ===
> 
> If you wanted to set up a Zoom call or something, I don't think IANA
> needs to be on it, but I could try to help set one up, if you wanted
> to suggest some times (without the list in copy).
> 
> thanks,
> Amanda
> 
> On Sat May 09 20:56:00 2026, [e-mail] wrote:
> > Sachin,
> >
> > We should probably get other reviewers to weigh in because I don't
> > think we are going to get alignment here.
> >
> > Let's ignore the CR/LF issue because it is a fairly esoteric
> > historical thing because as you say these things can be normalized
> > during transmission.
> >
> > You state,
> >
> > > YAML frontmatter — structured metadata containing AI-generated
> > > comprehension layers (summaries, voice script, ELI5 explanation).
> > > These are all plain natural language prose. They are not structured
> > > data
> >
> > From the specification https://github.com/gistmx/spec#quick-overview
> >
> >
> > mx_version: "1.1"
> > generated: "2026-03-05T12:00:00Z"
> > source: "README.md"
> > source_hash:
> > "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
> > model: "qwen3-8b-instruct"
> >
> > ...
> >
> > signature:
> >   type: "jws"
> >   alg: "EdDSA"
> >   kid: "did:web:gist.mx#mx-signing-key-1"
> >   issuer: "https://gist.mx"
> >   issued_at: "2026-03-05T12:00:01Z"
> >   claims_version: "mxsig-1"
> >
> > That really doesn't look like "natural language prose". I acknowledge
> > that some of the key/value pairs use natural language as a value, but
> > that doesn't remove the fact that the key name carries semantics that
> > are expected to be understood by a consuming application.
> >
> > > But in the frontmatter convention, YAML is simply a structured
> > > container for human-readable text fields — not executable
> > > instructions, not binary data, not application-specific processing
> > > directives.
> >
> > From this site https://www.markdownlang.com/advanced/frontmatter.html
> > > Frontmatter is a way to add metadata to your Markdown documents
> > > using
> > > YAML, TOML, or JSON at the beginning of the file. It's widely used
> > > in
> > > static site generators and content management systems.
> >
> > To paraphrase, frontmatter is metadata used by applications that
> > understand that metadata. Yes, frontmatter is used by Gatsby, Hugo,
> > Jeykll. The difference is, they are not trying to register a media
> > type to communicate that a specific document contains a specific set
> > of metadata.
> >
> > > 2.2 The text/calendar and text/vcard precedents directly refute
> > > this
> > > argument
> >
> > text/calendar and text/vcard were first registered back in 1998 when
> > the primary mode of transfer of these types was via MIME.  XML has a
> > text/xml media type because early clients didn't know how to render
> > application/xml. Early drafts of JSON referred to text/json because
> > the argument was made that a human can read the text. But both JSON
> > and YAML are only registered as an application type because those
> > formats are defined for applications to read.  If the semantics of
> > gist.mx were only intended for a human, or LLM, then the content
> > could
> > be written in prose with a markdown heading ## gist. Or it could be
> > put in an appendix of the document. Frontmatter yaml would not be
> > necessary and the media type could simply be text/markdown.
> >
> > > Use case 1: AI agent HTTP content negotiation.
> >
> > I'm a bit confused by the example you show with this accept header:
> >
> > > Accept: text/markdown, text/plain;q=0.9, */*;q=0.1
> >
> > This isn't the accept header that the acceptmarkdown.com site is
> > suggesting, and what is shown above would actually allow a site to
> > return application/gist.mx because it includes *.*.  Unless agents
> > start sending text/* then no content negotiation is going to return
> > text/vnd.gist.mx.  I see no indication that that is a plan from the
> > site you shared.
> >
> > > Use case 2: Git and version control systems.
> >
> > Yes, the fact that some applications only render types they know of
> > and text/* types is definitely an advantage using a text type.
> > However, if that is an important use case for you, and as you claim,
> > only humans are going to consume this front matter, then it is not
> > clear to me why  you want to register a media type at all and why you
> > wouldn't just use text/markdown as your media type.
> >
> > > Use case 3: Email and messaging systems.
> >
> > While the argument for email systems showing text/* content inline
> > does have an appeal, it highlights why vCard or iCal should not have
> > been text/* types because every time I have received a vCard or
> > iCalendar in email they have been delivered as an attachment.
> >
> > > Use case 4: The format is designed to be read by humans in plain
> > > text
> > > editors
> >
> > If so, then use text/markdown because the media type is providing
> > zero
> > value, because the human will almost never see it. And I don't know
> > what value the front matter is bringing because, for example, plain
> > text editors won't do text to speech on the "voice_brief" metadata.
> >
> > > Use case 5: The format is an open standard, not an application
> > > format.
> >
> > You seem to be misunderstanding the meaning of the application type.
> > It does not mean that the type is defined for use by a single
> > application.  That majority of the media type registrations under the
> > application type are open standards.
> >
> > My pushback on this registration is not specific to this scenario.
> > This registration would set an undesirable precedent for anyone else
> > that decided they had some specific metadata they wanted to add to a
> > markdown document.  Based on the feedback so far, I would suggest not
> > creating a media type, but instead use text/markdown. It might be
> > viable to follow the convention set here
> > https://www.markdownlang.com/advanced/frontmatter.html#seo-and-
> > social-
> > media where a "og:" prefix is used to namespace properties.  It seems
> > like a "gist:" prefix could be used in frontmatter properties to
> > identify the specific semantics.  This would allow markdown documents
> > to contain other frontmatter as well as gist related frontmatter.
> >
> > Darrel
> >
> > ________________________________
> > From: Amanda Baber via RT <[e-mail]>
> > Sent: Monday, May 4, 2026 10:31 PM
> > Cc: [e-mail] <[e-mail]>; Darrel Miller
> > <[e-mail]>
> > Subject: [IANA #1445779] text/vnd.gist.mx registration request
> >
> > Hi Darrel,
> >
> > The requester has sent an argument for not moving to application. See
> > below.
> >
> > =====
> >
> > * Response to Objection 1: CRLF / Line Ending Constraint
> >
> > The first reviewer (April 8) noted that our specification states both
> > LF and CRLF are supported, which is inconsistent with RFC 2046 §4.1.1
> > for text/* types.
> >
> > We accept this point and will correct the specification.
> >
> > We will update the specification to state:
> >
> > MX files use LF (0x0A) line endings. CRLF line endings MUST be
> > normalized to LF before processing. Implementations generating MX
> > files MUST use LF. Implementations receiving MX files via protocols
> > that canonicalize to CRLF (e.g., SMTP) MUST accept CRLF but SHOULD
> > normalize to LF for storage.
> >
> > This is the same approach used by text/markdown (RFC 7763) and
> > text/calendar (RFC 5545), both of which are text/* types that in
> > practice encounter both line ending conventions but specify
> > normalization behavior rather than rejecting the text/ tree. We are
> > willing to update the published specification before the registration
> > is finalized.
> >
> > This objection is resolvable and should not be the basis for moving
> > to
> > application/.
> >
> > * Response to Objection 2: "All semantic value is in the frontmatter,
> > not in the natural language text"
> >
> > This is the substantive disagreement and we would like to address it
> > carefully.
> >
> > - 2.1 The reviewer's premise is incorrect
> >
> > The reviewer states: "All of the semantic value of the proposed media
> > type vnd.gist.mx is in the frontmatter, not in the natural language
> > text."
> >
> > This mischaracterizes the format. An MX file has two parts:
> >
> > YAML frontmatter — structured metadata containing AI-generated
> > comprehension layers (summaries, voice script, ELI5 explanation).
> > These are all plain natural language prose. They are not structured
> > data in the sense of machine-executable instructions, schema
> > definitions, or binary-encoded information. They are sentences and
> > paragraphs written in human language, stored in YAML scalar fields.
> > Markdown body — the complete original source document, unchanged.
> > Both parts are natural language text. The YAML frontmatter contains
> > metadata fields whose values are plain prose. This is functionally
> > identical to the YAML frontmatter convention used by Jekyll, Hugo,
> > GitHub Docs, Obsidian, and hundreds of other tools — a convention so
> > widespread that it is explicitly documented by GitHub as their own
> > authoring standard (https://docs.github.com/en/contributing/writing-
> > for-github-docs/using-yaml-frontmatter).
> >
> > The reviewer may be thinking of YAML as inherently application-type
> > because of its use in configuration files and data exchange. But in
> > the frontmatter convention, YAML is simply a structured container for
> > human-readable text fields — not executable instructions, not binary
> > data, not application-specific processing directives.
> >
> > - 2.2 The text/calendar and text/vcard precedents directly refute
> > this
> > argument
> >
> > If the reviewer's argument were applied consistently, it would
> > invalidate two long-standing text/* registrations:
> >
> > text/calendar (RFC 5545): iCalendar is registered as text/calendar.
> > Its content is highly structured — it defines events, recurrences,
> > time zones, alarms, attendees, organizer roles, and scheduling
> > semantics. Every calendar application must parse and interpret this
> > structured data to be useful; a plain text display of a .ics file is
> > essentially meaningless to a human reader. The reviewer's argument —
> > "the application cannot provide value without understanding the
> > structured content" — applies identically to iCalendar. Yet it is
> > text/calendar, not application/calendar.
> >
> > text/vcard (RFC 6350): vCard is registered as text/vcard. It defines
> > structured contact information: names, phone numbers, email
> > addresses,
> > postal addresses, organizational roles, photographs (as base64). Like
> > iCalendar, a plain text display of a vCard file is navigable but
> > requires structured parsing to be useful for its primary purpose
> > (importing contacts). The RFC 6350 registration notes that
> > applications include "mail user agents, instant messaging clients,
> > address book applications, directory servers, and customer
> > relationship management software" — all of which must structurally
> > interpret the content. Yet it is text/vcard.
> >
> > The MX format is less structurally complex than either of these. Our
> > frontmatter fields are plain prose values in simple scalar YAML
> > fields. If text/calendar and text/vcard belong in text/,
> > text/vnd.gist.mx belongs there too.
> >
> > - 2.3 The reviewer's suggested alternative is technically incorrect
> >
> > The reviewer suggests: "application/vnd.gist.mx+markdown if such a
> > suffix existed."
> >
> > The +markdown structured syntax suffix does not exist in the IANA
> > Structured Syntax Suffixes registry. Registering a type that
> > references a non-existent suffix would introduce ambiguity rather
> > than
> > clarify semantics. We are not in a position to simultaneously
> > register
> > a new structured syntax suffix and a media type that uses it — that
> > would be a multi-year standards process, not a vendor-tree
> > registration.
> >
> > Furthermore, application/ is the wrong signal for this content. Per
> > RFC 2046 §4, the application/ type is appropriate for "data to be
> > processed by some type of application program." MX files are not
> > application-processed data in that sense — they are human-readable
> > documents. The markdown body is written to be read by humans. The
> > frontmatter summaries are written in natural language to be read by
> > humans. The voice brief script is written to be spoken aloud to
> > humans. This is a writing and reading format, precisely as RFC 7763
> > describes markdown: "Markdown is a writing format."
> >
> > - 2.4 The text/ prefix is essential for ecosystem adoption — and this
> > is not merely a convenience argument
> >
> > The reviewer's final question is: "Maybe it would be helpful if the
> > requestor can explain why it would be better for their users if this
> > media type had the text/ prefix."
> >
> > We will answer this directly and concretely.
> >
> > Use case 1: AI agent HTTP content negotiation.
> >
> > AI agents and LLM-based tools routinely send Accept: text/markdown
> > (per RFC 7763) to request markdown versions of resources. An emerging
> > convention (documented at https://acceptmarkdown.com
> > <https://acceptmarkdown.com/>) has agents sending:
> >
> > Accept: text/markdown, text/plain;q=0.9, */*;q=0.1
> >
> > The .mx format is a superset of text/markdown — it is the natural
> > upgrade path. If .mx is registered as application/, it will never
> > appear in these Accept headers without explicit effort, because
> > agents
> > are looking for text/* content types. text/vnd.gist.mx fits naturally
> > into the established Accept: text/markdown negotiation ecosystem.
> > application/vnd.gist.mx does not, and would require every agent
> > implementation to be specifically updated to request it.
> >
> > Use case 2: Git and version control systems.
> >
> > Git, GitHub, GitLab, and Gitea use the Content-Type or file extension
> > to determine how to render files in pull requests, code review
> > interfaces, and file browsers. These systems treat text/* files as
> > renderable text with diffs. An application/* type is typically
> > treated
> > as a binary blob — shown as "Binary file not shown" in git diffs. MX
> > files are intended to be committed alongside .md files in version-
> > controlled repositories and reviewed in pull requests. Registering as
> > application/ would break this workflow entirely.
> >
> > Use case 3: Email and messaging systems.
> >
> > The iCalendar ecosystem (text/calendar) demonstrated that text/*
> > registrations for structured formats enable email clients, messaging
> > systems, and collaboration tools to render content inline rather than
> > as attachments. If a developer sends an .mx file via email or
> > attaches
> > it in a Slack message, text/* hints to the client that the content is
> > human-readable and can be rendered inline. application/* hints that
> > specialized software is required to interpret it, discouraging inline
> > rendering.
> >
> > Use case 4: The format is designed to be read by humans in plain text
> > editors — not consumed by applications.
> >
> > The core design principle of .mx is backward compatibility. Any plain
> > text editor — Vim, Emacs, VS Code, Notepad — can open an .mx file and
> > a human can read it. The YAML frontmatter fields are labeled
> > oneliner,
> > gist, eli5, voice_brief — they are self-evidently human-readable
> > prose. The format specification explicitly states: "Any application
> > that processes standard markdown with YAML frontmatter can open and
> > render an MX file, displaying the frontmatter as metadata and the
> > body
> > as rendered markdown. MX-unaware applications will simply ignore the
> > comprehension layer fields in the frontmatter."
> >
> > This is the opposite of an application/* type. The content is human-
> > readable at rest, by design, without any application-specific
> > processing.
> >
> > Use case 5: The format is an open standard, not an application
> > format.
> >
> > The reviewer says: "If the authors believe that the important part of
> > the document is the natural language content then they should
> > encourage people to use the text/markdown media type and allow
> > applications to detect the front matter independently of media type."
> >
> > We understand this perspective, but it defeats the purpose of media
> > type registration. If we do not register a media type, there is no
> > standard way for any two implementations to agree on what an .mx file
> > is. The entire point of registering text/vnd.gist.mx is so that any
> > third-party tool — a markdown editor, a documentation generator, a
> > content management system, a static site generator — can add .mx
> > support by implementing against a stable, registered media type. The
> > gist.mx service is one implementation, but the format is open (CC BY
> > 4.0) and intended for widespread implementation. Registering as text/
> > signals that this is a text-based, human-readable format that any
> > text
> > tool can participate in. Registering as application/ signals that
> > only
> > specialized applications should handle it, which directly contradicts
> > the open-format vision.
> >
> > We respectfully request that the reviewer reconsider the objection to
> > text/ in light of the text/calendar, text/vcard precedents, and the
> > practical adoption considerations above. We are happy to update the
> > specification to address the CRLF constraint and to provide any
> > additional clarification requested.
> >
> > Thank you for your continued assistance with this registration.
> >
> > Thanks.
> >
> > Sachin
> >
> > =====
> >
> > thanks,
> > Amanda
> >
> > On Wed Apr 15 12:06:17 2026, [e-mail] wrote:
> > > From the specification:
> > >
> > > > The Markdown Experience (.mx) format extends standard markdown
> > > > with
> > > > structured AI-generated comprehension layers embedded in YAML
> > > > frontmatter. It makes markdown documents accessible by providing
> > > > multiple levels of understanding
> > >
> > > An application cannot provide these multiple levels of
> > > understanding
> > > without understanding the structured content.  The fact that
> > > applications can fall back to simple markdown rendering doesn't
> > > lead
> > > us to register this as a text/* type.  It would suggest
> > > application/vnd.gist.mx+markdown if such a suffix existed.
> > >
> > > All of the semantic value of the proposed media type vnd.gist.mx is
> > > in
> > > the frontmatter, not in the natural language text.  If the authors
> > > believe that the important part of the document is the natural
> > > language content then they should encourage people to use the
> > > text/markdown media type and allow applications to detect the front
> > > matter independently of media type.  As soon as the decision is
> > > made
> > > to create a new media type to convey new semantics, then we should
> > > focus on those semantics.  All of those semantics are in YAML
> > > frontmatter.
> > >
> > > Maybe It would be helpful if the requestor can explain why it would
> > > be
> > > better for their users if this media type had the text/ prefix.
> > >
> > > Darrel
> > > ________________________________
> > > From: Amanda Baber via RT <[e-mail]>
> > > Sent: Monday, April 13, 2026 14:29
> > > Cc: [e-mail] <[e-mail]>; Darrel Miller
> > > <[e-mail]>
> > > Subject: [IANA #1445779] text/vnd.gist.mx registration request
> > >
> > > Hi Darrel,
> > >
> > > Response from the author:
> > >
> > > "We would like to keep it under text since all the contents of the
> > > mx
> > > files are markup text. If we should remove support for CrLF line
> > > endings we can add that to be reviewed under text. The mx
> > > conversion
> > > is not application specific, any application can use this framework
> > > to
> > > create mx files."
> > >
> > > Can this continue to use text? If so, do they need to make changes
> > > to
> > > the registration template?
> > >
> > > thanks,
> > > Amanda
> > >
> > > On Wed Apr 08 12:14:32 2026, [e-mail] wrote:
> > > > Hi Amanda,
> > > >
> > > > Here is my review of this registration request.
> > > >
> > > > 1. The author should change the type from text/ to application/.
> > > > The
> > > > text/ top-level type carries CRLF and charset constraints (RFC
> > > > 2046
> > > > §4.1.1, RFC 6657 §3) that are unnecessarily burdensome for this
> > > > format. application/vnd.gist.mx avoids those issues. Specifically
> > > > the
> > > > specification states that both LF and CR/LF are supported which
> > > > is
> > > > not
> > > > consistent with the definition of text/* types.
> > > >
> > > > Darrel
> > > >
> > > > ________________________________
> > > > From: Amanda Baber via RT <[e-mail]>
> > > > Sent: Wednesday, April 01, 2026 19:09
> > > > Cc: [e-mail] <[e-mail]>; Darrel Miller
> > > > <[e-mail]>
> > > > Subject: [IANA #1445779] text/vnd.gist.mx registration request
> > > >
> > > > Hi Darrel,
> > > >
> > > > Sending a reminder for this request from March 9th.
> > > >
> > > > thanks,
> > > > Amanda
> > > >
> > > > On Mon Mar 09 23:32:21 2026, amanda.baber wrote:
> > > > > Hi Darrel,
> > > > >
> > > > > Would it be possible to review this for us by March 23rd?
> > > > >
> > > > > thanks,
> > > > > Amanda
> > > > >
> > > > > =====
> > > > >
> > > > > Name: Sachin Nagda
> > > > >
> > > > > Email: [e-mail]
> > > > >
> > > > > Media type name: text
> > > > >
> > > > > Media subtype name: vnd.gist.mx
> > > > >
> > > > > Required parameters: N/A
> > > > >
> > > > > Optional parameters: charset: Specifies the character encoding
> > > > > of
> > > > > the
> > > > > content. If omitted, UTF-8 is
> > > > > assumed, consistent with modern markdown processing. The
> > > > > charset
> > > > > parameter
> > > > > follows the same conventions defined in RFC 6657 for textual
> > > > > media
> > > > > types.
> > > > >
> > > > > version: Indicates the version of the MX format specification
> > > > > that
> > > > > the
> > > > > file
> > > > > conforms to. The value is a dotted decimal version number
> > > > > (e.g.,
> > > > > "1.0").
> > > > > If omitted, version "1.0" is assumed.
> > > > >
> > > > > Encoding considerations: 8bit
> > > > >
> > > > > MX files are UTF-8 encoded plain text consisting of YAML
> > > > > frontmatter
> > > > > delimited
> > > > > by "---" lines, followed by a standard markdown document body.
> > > > > The
> > > > > format does
> > > > > not contain NUL octets, binary data, or lines exceeding 998
> > > > > octets
> > > > > under normal
> > > > > usage. Content is line-oriented text separated by CRLF or LF
> > > > > line
> > > > > endings.
> > > > >
> > > > > In rare cases where the embedded markdown body contains very
> > > > > long
> > > > > lines (e.g.,
> > > > > base64-encoded inline images in markdown or extremely long
> > > > > URLs),
> > > > > lines may
> > > > > exceed 998 octets. Implementations generating such content
> > > > > should
> > > > > use
> > > > > Content-Transfer-Encoding of "binary" or "quoted-printable"
> > > > > when
> > > > > transmitting
> > > > > via protocols that impose line length limits (e.g., SMTP).
> > > > >
> > > > > Security considerations: 1. Active/executable content: MX files
> > > > > do
> > > > > not
> > > > > contain active or executable
> > > > > content. The format consists entirely of UTF-8 text: YAML
> > > > > frontmatter
> > > > > metadata fields followed by a markdown document body. No
> > > > > scripting,
> > > > > macros, or executable instructions are defined by the format.
> > > > > However,
> > > > > the markdown body may contain raw HTML if the source markdown
> > > > > includes
> > > > > it. Consumers that render embedded HTML should apply the same
> > > > > sanitization practices used for standard markdown rendering
> > > > > (e.g.,
> > > > > stripping <script> tags, disallowing event handlers).
> > > > >
> > > > > 2. Privacy and integrity: MX files may contain AI-generated
> > > > > comprehension
> > > > > layers (summaries, voice scripts, explanatory text) derived
> > > > > from
> > > > > the
> > > > > source markdown. These layers could inadvertently disclose
> > > > > sensitive
> > > > > information from the source document in a more accessible form.
> > > > > The
> > > > > format itself includes a source_hash field (SHA-256) that
> > > > > allows
> > > > > consumers to verify whether the comprehension layers correspond
> > > > > to
> > > > > a specific source document, providing a basic integrity check.
> > > > > The format does not provide encryption or digital signature
> > > > > mechanisms.
> > > > >
> > > > > 3. External privacy/integrity services: For documents requiring
> > > > > confidentiality or tamper detection, standard transport-layer
> > > > > security
> > > > > (TLS) should be used for transmission, and external signing
> > > > > mechanisms
> > > > > (e.g., PGP, S/MIME) can be applied to the file as with any text
> > > > > document.
> > > > >
> > > > > 4. Underlying format considerations: MX files use YAML (in the
> > > > > frontmatter)
> > > > > and markdown (in the body), both of which are well-established
> > > > > text
> > > > > formats. YAML parsing carries known security considerations:
> > > > > consumers
> > > > > MUST use safe YAML loading (e.g., YAML.safeLoad or equivalent)
> > > > > to
> > > > > prevent code execution through YAML deserialization attacks.
> > > > > The
> > > > > frontmatter section is constrained to simple scalar values,
> > > > > sequences,
> > > > > and mappings; no YAML tags, anchors, or aliases are used in the
> > > > > format
> > > > > specification.
> > > > >
> > > > > 5. The format may reference an external audio file via the
> > > > > voice_brief.audio_hash field. This is a content hash, not a
> > > > > URL;
> > > > > it does not create an automatic external reference. Consumers
> > > > > that
> > > > > resolve audio files should verify the hash matches the
> > > > > retrieved
> > > > > content.
> > > > >
> > > > > 6. The guidance section (in version 2.0 of the format) may
> > > > > contain
> > > > > author-attributed metadata including the author's name and
> > > > > editorial
> > > > > guidance. This constitutes personal data and should be handled
> > > > > in
> > > > > accordance with applicable data protection regulations.
> > > > >
> > > > > Interoperability considerations: MX files are designed for
> > > > > maximum
> > > > > backward compatibility with existing
> > > > > markdown tooling. An MX file is structurally identical to a
> > > > > markdown
> > > > > file
> > > > > with YAML frontmatter, a pattern widely supported by static
> > > > > site
> > > > > generators
> > > > > (Jekyll, Hugo, Gatsby), documentation tools (MkDocs,
> > > > > Docusaurus),
> > > > > and
> > > > > text
> > > > > editors (VS Code, Obsidian, Typora).
> > > > >
> > > > > Any application that processes standard markdown with YAML
> > > > > frontmatter
> > > > > can
> > > > > open and render an MX file, displaying the frontmatter as
> > > > > metadata
> > > > > and
> > > > > the
> > > > > body as rendered markdown. MX-unaware applications will simply
> > > > > ignore
> > > > > the
> > > > > comprehension layer fields in the frontmatter.
> > > > >
> > > > > MX-aware applications additionally parse the frontmatter to
> > > > > extract
> > > > > and
> > > > > display the structured comprehension layers (oneliner, gist,
> > > > > voice_brief,
> > > > > eli5) and may resolve the associated audio content.
> > > > >
> > > > > The YAML frontmatter conforms to the YAML 1.2 specification and
> > > > > uses
> > > > > only
> > > > > the JSON-compatible subset (scalars, sequences, mappings). The
> > > > > markdown
> > > > > body follows the CommonMark specification with GitHub Flavored
> > > > > Markdown
> > > > > (GFM) extensions.
> > > > >
> > > > > Line endings may be either CRLF or LF. Consumers should accept
> > > > > both.
> > > > >
> > > > > Published specification: The MX format specification is
> > > > > published
> > > > > and
> > > > > maintained at:
> > > > >
> > > > > https://www.gist.mx/#spec
> > > > >
> > > > > The specification defines:
> > > > > - The YAML frontmatter schema (required and optional fields)
> > > > > - The five comprehension layers and their constraints
> > > > > - The source hash verification mechanism
> > > > > - The multi-file project MX variant
> > > > > - JSON Schema for frontmatter validation
> > > > >
> > > > > The specification source is additionally available in the
> > > > > project's
> > > > > public GitHub repository:
> > > > >
> > > > > https://github.com/gistmx/spec/tree/main/v1
> > > > >
> > > > > Applications which use this media: The MX format is used by the
> > > > > gist.mx platform and associated tools for
> > > > > creating, distributing, and consuming AI-enriched markdown
> > > > > documents.
> > > > >
> > > > > Applications that produce MX files:
> > > > > - gist.mx web application (https://gist.mx)
> > > > > - @gistmx/cli command-line tool (published on npm)
> > > > > - gistmx/convert-action GitHub Action
> > > > > - gist.mx REST API
> > > > >
> > > > > Applications that consume MX files:
> > > > > - gist.mx web viewer (renders all comprehension layers with
> > > > > audio
> > > > > playback)
> > > > > - gist.mx mobile applications (iOS and Android)
> > > > > - Any standard markdown editor or viewer (backward-compatible
> > > > > rendering)
> > > > > - Any YAML-aware text editor (frontmatter is valid YAML)
> > > > >
> > > > > The format is also designed for use in CI/CD pipelines where MX
> > > > > files
> > > > > are
> > > > > auto-generated alongside source markdown files in version-
> > > > > controlled
> > > > > repositories.
> > > > >
> > > > > Fragment identifier considerations: Fragment identifiers for MX
> > > > > files
> > > > > follow the same conventions as for
> > > > > text/markdown (RFC 7763). Fragment identifiers reference
> > > > > sections
> > > > > of
> > > > > the
> > > > > rendered markdown body using heading-derived anchors (e.g.,
> > > > > #section-
> > > > > name).
> > > > >
> > > > > Additionally, MX-aware consumers may recognize the following
> > > > > fragment
> > > > > identifiers for navigating to specific comprehension layers:
> > > > >
> > > > > #mx-oneliner - Navigate to the one-liner layer
> > > > > #mx-gist - Navigate to the core gist layer
> > > > > #mx-voice - Navigate to the voice brief layer
> > > > > #mx-eli5 - Navigate to the ELI5 layer
> > > > > #mx-full - Navigate to the full document body
> > > > >
> > > > > These layer fragment identifiers are advisory. MX-unaware
> > > > > consumers
> > > > > will
> > > > > ignore them, consistent with standard fragment identifier
> > > > > handling
> > > > > for
> > > > > unknown fragments.
> > > > >
> > > > > Restrictions on usage: N/A. The MX format may be used in any
> > > > > context
> > > > > where text/markdown is
> > > > > appropriate. No restrictions on protocol or application
> > > > > context.
> > > > >
> > > > > Provisional registration? (standards tree only): No
> > > > >
> > > > > Additional information:
> > > > >
> > > > > 1. Deprecated alias names for this type: N/A
> > > > > 2. Magic number(s): The byte sequence 0x2D 0x2D 0x2D 0x0A
> > > > > (ASCII:
> > > > > "---
> > > > > \n") at position 0 followed by the string "mx_version:" within
> > > > > the
> > > > > first 256 bytes. The leading "---" is the YAML frontmatter
> > > > > delimiter,
> > > > > and the presence of "mx_version" within the frontmatter
> > > > > distinguishes
> > > > > MX files from standard markdown with YAML frontmatter.
> > > > > 3. File extension(s): .mx
> > > > > 4. Macintosh file type code: TEXT
> > > > > 5. Object Identifiers: N/A
> > > > >
> > > > > General Comments: The MX (Markdown Experience) format extends
> > > > > standard
> > > > > markdown with
> > > > > structured AI-generated comprehension layers embedded in YAML
> > > > > frontmatter.
> > > > > It is designed to make markdown documents more accessible by
> > > > > providing
> > > > > multiple levels of understanding: a single-sentence summary, a
> > > > > short
> > > > > gist,
> > > > > a conversational voice-ready script, and a simplified
> > > > > explanation.
> > > > >
> > > > > The format prioritizes backward compatibility: any tool that
> > > > > reads
> > > > > markdown
> > > > > with YAML frontmatter can process MX files without
> > > > > modification.
> > > > > The
> > > > > additional comprehension layers are purely additive metadata.
> > > > >
> > > > > The MX format specification is versioned (starting at 1.0) and
> > > > > includes
> > > > > provisions for future extensions including guided authoring
> > > > > metadata
> > > > > and
> > > > > edit history tracking.
> > > > >
> > > > > The ".mx" file extension does not conflict with any currently
> > > > > registered
> > > > > IANA media type file extension.
> > > > >
> > > > > Person to contact for further information:
> > > > >
> > > > > 1. Name: Sachin Nagda
> > > > > 2. Email: [e-mail]
> > > > >
> > > > > Intended usage: COMMON
> > > > >
> > > > > Author/Change controller: Sachin Nagda, gist.mx