Markdown for XML2RFC v3

November 27, 2014


Or… how to write Markdown to generate XML that is valid XML2RFC v3. These are some assorted notes and ideas


  1. Self contained file with all information to generate a complete I-D;
  2. CommonMarkdown, with some extension.

I’m working on implementing these ideas in blackfriday. The following has already been implemented:

  • Abstract;
  • Citation;
  • Document divisions;
  • Index;
  • File inclusion;
  • Extra attributes (kramdown’s IAL.) (work-in-progress).

Document meta data

In TOML - much easier than YAML for instance, lines are starting with %. We don’t need to specify the citations here because:


Use the reference syntax: [p. 23][#RFC2535], which can be extended to include a filename where the reference is:

[p. 23][#RFC2335,bib/reference.RFC.2525.xml]

They can optionally have ‘n’ or ‘i’ modifier to normative or informative reference. The reference section is automatically generated. Here is a normative and informative reference:


The default is informative. This only have to be done once, after that you can just use [][#RFC2535].

Abstract, notes and asides

Abstract is done with prefixing a paragraph with AB>, notes: N> and aside with A>.

Extra Attributes

CommonMark (seems?) to have adapted the kramdown IAL syntax but dropped the colon, so we would use {.class key=value} to add attributes to block elements.

Document Divisions

The front-, middle- and back-sections are signalled with:

{frontmatter}, {middlematter} and {backmatter}, where a document automatically starts with a frontmatter.


Using triple parentheses, like so: (((Cats, Tiger))).

Including Markdown files

Use the syntax {{file}} will get file included.

All of the above use the extension syntax, i.e. starting with a { .

Quotes attribution?

> this is an quote
-- Miek Gieben

BCP14 keywords?

Uppercase in asterisks *MUST*.

XML  CommonMark  Markdown  XML2RFC  Mmark