- Vladimirs Nordholm
RFC-CSS: Semantic RFC-like documents
Abstract
RFC-CSS is a CSS library for creating authentic-looking RFC documents from semantic HTML. Designed to integrate with Markdown-generated content. Design decisions are primarily taken from [RFC3339], but other RFCs are also used for inspiration.
Additional attributes can be used to achieve extra features; either by inserting HTML directly into the Markdown file, or by using a pre-processor.
This page has interactive elements to further demonstrate the features of RFC-CSS.
Introduction
Releases are available on the GitHub repository [RFC-CSS].
Include the CSS file in your HTML document:
<link rel=stylesheet href=...>
To create a document that looks like an RFC, you need to add the following data attribute to your root RFC document element.
<body data-rfc>
Optionally, you may add the following custom CSS-rule to your document to add the same margins as the IETF RFCs have:
[data-rfc] {
margin: 0 4em;
}
Headings
The style of the heading is controlled by the data-rfc-heading attribute. If the attribute is set on the heading, or any of its parent elements, the heading will be styled accordingly.
By default, headings are bolded and un-numbered. The styles are: “plain”, un-numbered and un-bolded; “counter”, bolded and numbered; nothing for default style.
Heading number spacing
The spacing between the number and the heading text is controlled by the --rfc-heading-spacing CSS variable, with the default value of 1ch.
Examples
To change the spacing between the number and the heading text, change the CSS variable:
<h3 style='--rfc-heading-spacing: 3ch' id=h-demo>Examples</h3>
To make all headings in a document numbered, add the following attribute to the document root element:
<body data-rfc =>To only set the style for a specific heading, add the attribute to the heading element itself:
<h2 data-rfc-heading=plain id=abstract>Abstract</h2>
<h2 data-rfc-heading id=introduction>Introduction</h2>
Tables
Regular tables are supported.
| Type | Table | Caption | Ease of use |
|---|---|---|---|
| Markdown | x | x | |
| HTML | x | x |
Features available
Optionally, a caption can be added to the table by wrapping the table in a <figure>-element with an accompanying <figcaption>-element.
NOTE: The table style is based of tables in [RFC7555].
Lists
The type of lists supported are:
- unordered lists,
<ul>
- ordered lists,
<ol>
- definition lists
- only available with HTML, and gives different appearance when wrapped with `<div>`-tags.
Ordinary lists
This section refers to ordered an unordered lists.
The marker for unordered lists is defined with the CSS variable --rfc-list-marker, which has a default value of "o ".
Examples
Spacing between items
To have spacing between list items, wrap the content in the list item with a paragraph.
<ol>
<li><p>foo</p></li>
<li><p>bar</p></li>
<li><p>baz</p></li>
</ol>
… or with Markdown, include blank lines between items:
1. foo
1. bar
1. baz
Custom markers
To change the markers to - for unordered lists, change the CSS variable --rfc-list-marker.
<ul style=': ""'>- foo
- bar
- baz
NOTE: The spacing between the marker and the item is defined by the whitespace in the marker itself.
Images
Although never used in RFC documents, images are supported.
Ozzy taking her Monday nap
Similar to tables, a caption can be added to the image by wrapping the image in a <figure>-element with an accompanying <figcaption>-element.
Images can also cover the entire width of the page by not wrapping the image in any element.
This page
The entire page is 72 characters wide. On mobile devices, or small displays in general, the page shrinks accordingly.
Pre-defined structure
At the top of the page, the navigation and header use custom attributes and a specific layout.
<nav data-rfc-navigation>
<ul>
<li><a href="/">home</a></li> ...
</ul>
<span>BLOG POST</span>
</nav>
<header data-rfc-header>
<ul>
<li id="tags">Tags: ...</li>
</ul>
<ul>
<li>Vladimirs Nordholm</li>
<li>...</li>
</ul>
</header>
Pre-processing
On this site there are some additional pre-processing happening to better create a more fulfilling experience. Some design choices of RFC documents are not possible to handle with CSS alone.
Titles are adjusted with a trailing space " " when having an odd number of characters, to compensate for half-character centering.
After each period ".", a custom “double space” is inserted:
<span data-rfc-double-space> </span>. It appears to be two spaces after the period, but is only a single space when selected.
Additional CSS
WIP…
CSS variable glossary
--rfc-term-width- Width of terms in definition lists, when not wrapped in
<div>-tags. --rfc-content-indentation- Indentation of content; used for majority of elements.
--rfc-heading-spacing- Spacing between heading numbering and text.
--rfc-list-marker- Marker for unordered lists.
--rfc-line-height- Line height of the text.
References
- [RFC-CSS]
- Nordholm, V., "RFC-CSS", GitHub, March 2023.
- [RFC3339]
- Klyne, G., and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002.
- [RFC7555]
- Swallow, G., Lim, V., and S. Aldrin, "Proxy MPLS Echo Request", RFC 7555, June 2015.