A simplistic translation (a.k.a. Rosetta Stone) is below. For details and examples, please see:
| Concept | RFCXML | kramdown-rfc |
|---|---|---|
| Abstract, middle, back | <abstract> <middle> <back> | --- abstract--- middle--- back |
| Artwork in figure | <figure> <artwork>foo</artwork> </figure> | ~~~ foo ~~~ |
| Artwork with anchor | <figure title="Sample" anchor="sample-fig"> <artwork><![CDATA[ 0 1 2 3 +-+-+-+-+ | Label | +-+-+-+-+ ]]></artwork> </figure> | ~~~
0 1 2 3
+-+-+-+-+
| Label |
+-+-+-+-+
~~~
{: title="Sample" #sample-fig}
|
| SVG artwork | <figure>
<artset>
<artwork type="svg">
<svg...
{SVG code}
</svg>
</artwork>
<artwork type="ascii-art"><<![CDATA[
{ASCII artwork}
]]></artwork>
</artset>
</figure>
| ~~~ aasvg +----------+ | a box | +----------+ ~~~ Add “aasvg” to the ascii-art indicator (~~~) |
| Aside | <aside> | {:aside}
> foo
|
| Blockquote | <blockquote> | {:quote}
> foo
|
| Citation |
|
|
| Citation with section number | | |
| Citation with multiple section numbers | | |
| Section, figure, or table pointer | <xref target=“intro”/> | {{intro}}
where “intro” is the anchor for the Introduction section. |
| Point to multiple sections within the document | Sections <xref target=“iana_cons” format=“counter” /> and <xref target=“sec_cons” format=“counter” /> | Sections {{iana_cons}}{: format="counter"}
and {{sec_cons}}{: format="counter"}
|
| Comments | <!-- foo –-> | <!-- foo –-> or {::comment}foo{:/comment}
Note: The latter will not appear in the XML file after running xml2rfc. |
| Contact | <contact fullname=“Jane Doe”/> | {{{Jane Doe}}} |
| External reference (inline with angle brackets) | <eref target="https://example.com" brackets="angle"/> | [](https://example.com/){: brackets="angle"} |
| External reference (linked text) | <eref target=“https://example.com”>An example</eref> is blah. | [An example](https://example.com) is blah. |
| Index reference | <iref item=“Foo” /> | (((Foo))) |
| Indent text | <t indent=“3”>foo</t> | No direct equivalent. This yields indented text, but not the desired XML: > foo |
| List: Definition list | <dl>
<dt>First term:</dt>
<dd>First def</dd>
<dt>Second term:</dt>
<dd>
<t>Second def P1</t>
<t>Second def P2</t>
</dd>
</dl>
For same line: <dl newline="false"> | {:vspace}
First term:
: First def
For same line: omit the leading {:vspace}
|
| List: Ordered list | <ol> <li>Foo</li> <li>Bar</li> </ol> | 1. Foo 2. Bar
Note: For list items with multiple paragraphs, indent first line of |
| List: Unordered list | <ul> <li>Foo</li> <li>Bar</li> </ul> | * Foo * Bar or - Foo - Bar
Note: For list items with multiple paragraphs, indent first line of |
| Reference | [see below] | |
| Sourcecode with type | <sourcecode type=“abnf”> | ~~~ abnf foo ~~~ |
| Sourcecode with no type | <sourcecode type=“”> | ~~~
foo
~~~
{: gi="sourcecode"}
|
| Sourcecode in figure w/ markers and filename | <figure title="Sample">
<sourcecode type="xml"
markers="true"
name="sample.xml">
foo
</sourcecode>
</figure>
| ~~~ xml
foo
~~~
{: title='Sample' sourcecode-markers="true" sourcecode-name="sample.xml"}
|
| Section with anchor | <section anchor=“intro”> <name>Introduction</name> | # Introduction {#intro} |
| Section unnumbered with anchor | <section numbered=“false” anchor=“acks”> <name>Acknowledgements</name> | # Acknowledgments {#acks}
{:numbered="false"}
|
| Table with anchor | <table anchor="totals">
<name>Annual Totals</name>
<thead>
<th>Year</th><th>Total</th>
</thead>
<tbody>
<tr><td>2018</td><td>208</td></tr>
<tr><td>2019</td><td>180</td></tr>
</tbody>
</table>
| | Year | Total |
-------------------
| 2018 | 208 |
| 2019 | 180 |
{: title="Annual Totals" #totals}
|
| Table column alignment | <table>
<thead>
<th>Item #</th><th>Year</th><th>Total</th>
</thead>
<tbody>
<tr>
<td align="left">Item 1</td>
<td align="center">2018</td>
<td align="right">208</td>
</tr>
<tr>
<td align="left">Item 2</td>
<td align="center">2019</td>
<td align="right">180</td>
</tr>
</tbody>
</table
| | Item # | Year | Total | |:-------|:------:|-------:| | Item 1 | 2018 | 208 | | Item 2 | 2019 | 180 | Note: The headings will also correspond to the column alignment. |
| Text styling | <strong>bold</strong> <em>italics</em> <tt>fixed width</tt> |
**bold** *italics* `fixed width` |
| Subscript and superscript | W<sub>max</sub> 2<sup>16</sup> | [the same as XML] |
| Concept | RFCXML | kramdown-rfc |
|---|---|---|
| Document basics | <rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info" ipr="trust200902" docName="draft-foo-00" number="0000" consensus="true" obsoletes="YYYY" updates="ZZZZ" submissionType="IETF" tocInclude="true" symRefs="true" sortRefs="true" version="3" xml:lang="en"> | title: The Foo Protocol abbrev: FOOP number: 0000 docname: draft-foo-00 category: info submissiontype: IETF consensus: true ipr: trust200902 obsoletes: YYYY updates: ZZZZ pi: [toc, symrefs, sortrefs] v: 3 lang: en |
| More metadata | <date year=“2025” month=“July”/> <area>OPS</area> <workgroup>DNSOP</workgroup> <keyword>foo</keyword> <keyword>bar</keyword> | date: 2025-07 area: OPS workgroup: DNSOP keyword: - foo - bar |
| Author block | <author initials="J." surname="Doe" fullname="Jane Doe"
role="editor">
<organization>Acme</organization>
<address>
<postal>
<street>123 Main Street</street>
<city>Anytown</city>
<region>CA</region>
<Code>12345</Code>
<country>United States of America</country>
</postal>
<email>jdoe@example.com</email>
<uri> https://www.example.com</uri>
</address>
</author>
| author: - name: Jane Doe ins: J. Doe role: editor org: Acme street: 123 Main Street city: Anytown region: CA code: 12345 country: United States of America email: jdoe@example.com uri: https://www.example.com |
| Contributors block (if list of names with contact info | <contact fullname="Jane Doe" >
<organization>Acme</organization>
<address>
<postal>
<street>123 Main Street</street>
<city>Anytown</city>
<region>CA</region><Code>12345</Code>
<country>United States of America</country>
</postal>
<email>jdoe@example.com</email>
<uri>https://www.example.com</uri>
</address>
</contact>
| contributor: - name: Jane Doe ins: J. Doe org: Acme street: 123 Main Street city: Anytown region: CA code: 12345 country: United States of America email: jdoe@example.com uri: https://www.example.com |
| Comments | <!-- foo –-> | # foo Note: This will not appear in the XML file after running xml2rfc. |
See documentation on references for details.
| Concept | RFCXML | kramdown-rfc |
|---|---|---|
| Normative Ref | <xi:include href="https://bib.ietf.org/ public/rfc/bibxml/reference.RFC.9200.xml"/> | in the body: |
| Informative Ref | <xi:include href="https://bib.ietf.org/ public/rfc/bibxml/reference.RFC.8032.xml"/> <xi:include href="https://bib.ietf.org/ public/rfc/bibxml3/reference.I-D.ietf-mpls-rmr.xml"/> | in the body: |
| Non-RFC Ref | <reference anchor="X.690"
target="https://www.itu.int/rec/T-REC-X.690">
<front>
<title>Information technology - ASN.1 [...]</title>
<author>
<organization>ITU-T</organization>
</author>
<date year="2021" month="February"/>
</front>
<seriesInfo name="ITU-T" value="Recommendation X.690"/>
<seriesInfo name="ISO/IEC" value="8825-1:2021"/>
<refcontent>Ref content goes here</refcontent>
</reference>
| X.690:
target: https://www.itu.int/rec/T-REC-X.690
title: "Information technology - ASN.1 [...]"
date: 2021-02
author:
org: ITU-T
seriesinfo:
ITU-T: Recommendation X.690
ISO/IEC: 8825-1:2021
rc:
Ref content goes here
|
| A symbolic name using displayreference | <displayreference target=“RFC5234” to=“ABNF”/> <displayreference target=“I-D.ietf-mpls-rmr” to “RMR”/> | RFC5234: display: ABNF In the body, cite as: {{RFC5234}} and {{I-D.ietf-mpls-rmr}} |
| A symbolic name without displayreference | <reference anchor="ABNF"> <title>Augmented BNF for Syntax Specifications: ABNF</title> [...the rest of the RFC5234 ref from the citation library] | ABNF: RFC5234
In the body, cite as: {{ABNF}} |
| A de-aliased reference with symbolic name (kramdown-rfc only) | n/a | I-D.bormann-cbor-notable-tags:
-: notable
display: NOTABLE-TAGS
|