Abstract #

RFCs should be represented internally using the Markdown document format.

Background #

RFC Hub needs to store RFC content which is mostly text based but with some additional semantic fields and formatting as well.

Problem #

We need to choose a format to store RFC documents.

Proposal #

We will use GitHub flavored Markdown. This format is well understood by most modern software developers, which are the target audience of RFC Hub.

User Interface #

Editing an RFC will display content as Markdown. Users will type in things like # symbols to represent headings and so on. In the future we may switch to a more advanced editor with a toolbar to automate formatting, as well as a toggle switch to switch between editing Markdown and WSYIWYG.

When viewing an RFC the Markdown is to be rendered as normal HTML. This conversion should happen server-side so that HTML consuming entities (such as Browsers and Search Engines) get content formatted in a familiar manner.

Definition of success #

A developer will edit and render docs and confirm that it works. This needs to be tested in Firefox and Chrome.

Alternatives Considered #

Store as Plain Text #

The IETF RFC documents are essentially text-based. However it's nice to embed graphics, link to third party resources, and easily visualize headings. Overall the semantic nature of rendered HTML is something we want to support.

Store as HTML #

While HTML makes sense as a format to visualize it would be exceedingly difficult to properly store and sanitize this data. Basically there are only about a dozen HTML elements we want to support (H1...H6, A, STRONG, EM, etc) but HTML supports a lot more (SCRIPT, BODY, etc.).

Store as ASCIIDOC #

There are dozens of additional content storage formats that we could choose from. In the end the ubiquitous nature of Markdown makes it appealing. There are many reasons that users don't adopt new technologies and learning a new documentation language shouldn't be one of them.

Future Improvements #

• WYSIWYG editor
• Use the same renderer for previewing as with normal rendering