Rapido.css: semantic HTML for your writings.

Rapido provides a default style for a set of semantic HTML elements that you can use to compose your essays. Just write with semantic HTML, without the need to remember any CSS class or JS command.

The present document has been created using Rapido, you can easily get documents or blog posts with the same layout and style. See how to use Rapido in the next sections.

<article class="rapido">
  <section>
    <h1>...</h1>
    <p>...<small>...</small></p>
  </section>
</article>

Assign the CSS class rapido to the <article> element and you are done.

Rapido is just that: copy the HTML snippets and fill the gaps.

Rapido is open source, view it on Github.

Motivation

Having your own corner on the web where you can freely share thoughts or technical stuff is still cool, and the popularity of tools like Jekyll or Gatsby proves that. Rapido intervenes there, offering semantic HTML templates for a variety of typical author needs: like header, sections, side notes, references and so on.The importance of using semantic HTML is a common theme in web development, it is a good idea to use the relevant HTML element for the job. Semantic HTML improves the usability of the code and ensures maximum accessibility.

Rapido has been crafted with the idea that using semantic HTML for your writings can be easy. For such a reason Rapido does not make use of CSS classes or Javascript hooks, the author can compose all the different parts of the document with semantic HTML elements, for example adding side notes in paragraphs with the <small> element.

Getting started

Rapido provides style rules in the rapido.css stylesheet, you can see the latest version of the CSS file in Github. Use rapido.css linking to it within the <head> element in your document.

<head>
  <link href="https://unpkg.com/@nextbitlabs/rapido@^3/rapido.css" rel="stylesheet" type="text/css">
</head>

Link to rapido.css in unpkg. Rapido uses semantic versioning, the example fetches the major release 3.x.

The style rules defined in rapido.css are name-spaced under the CSS class rapido. Being Rapido thought for web essays, the place to use the CSS class is the <article> element, as showed in the next snippet.

<main>
  <article class="rapido">
    ...
  </article>
</main>

Assign CSS class rapido to the <article> element.

Rapido can be used in a web document created from scratch or within an existing document, the CSS class rapido makes Rapido not invasive with respect to existing CSS code.

Install with npm

Alternatively, you may want to install Rapido using npm. This is especially useful when you want to add Rapido as a dependency of your application.

npm install @nextbitlabs/rapido

Get your hands dirty

If you want to try Rapido then you need the skeleton of an HTML document. The next code snippet provides a minimal template, copy the snippet in a fresh HTML file.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no, user-scalable=yes">
    <link href="https://unpkg.com/@nextbitlabs/rapido@^3/rapido.css" rel="stylesheet" type="text/css">
  </head>
  <body>
    <main>
      <article class="rapido">
        ...
      </article>
    </main>
  </body>
</html>

Minimal skeleton of an HTML document.

Note the presence of the stylesheet rapido.css within the <head> element, it defines the style rules and it is all you need to use Rapido.

The next sections describe how to replace the ellipsis with the content of interest, like paragraphs, figures, tables and so on.

Sections

The previous code snippet shows a gap within the <article> element, you can fill the gap with sections. Typically, sections have a heading and one or more paragraphs. Moreover, sections may also contain figures, tables and much more.

<main>
  <article>
    <section>
      <h1>...</h1>
      <p>...</p>
      <p>...</p>
      <h2>...</h2>
      <p>...</p>
    </section>
  </article>
</main>

Code snippet of a section.

The example shows a section with a heading and two paragraphs, a lower level heading and another paragraph.

The code snippet above shows an example of implicit sectioning, where both the <h1> and <h2> elements are in the same section. Authors are encouraged to explicitly wrap sections in elements of sectioning content, instead of relying on the implicit sections generated by having multiple headings in one <section> element.

<main>
  <article>
    <section>
      <h1>...</h1>
      ...
      <section>
        <h2>...</h2>
        ...
        <section>
          <h3>...</h3>
          ...
        </section>
      </section>
    </section>
  </article>
</main>

Explicit sectioning.

Sections in HTML5 can be nested, use headings of the appropriate rank for the section's nesting level. Explicit sectioning allows for predictable document outlines and better user experience.

Title and abstract

The <header> element is used for the title and few introductory paragraphs of your document. Generally, it is placed as the first element within the <article> element.

<main>
  <article>
    <header>
      <h1>...</h1>
      <p>...</p>
      <p>...</p>
      <address>
        <img src="...">
        ...
        <a href="...">...</a>
      </address>
    </header>
    ...
  </article>
</main>

Code snippet for the document header.

The element <address> can be used to indicate the contact information of the authors. The element <img> is useful for adding the author avatar.

The header may also contain full-width images, as described in section Images and videos.

Side comments

This section describes how to add a side comment. Side comments typically show parenthetical content considered part of the main flow, like qualifying remarks directly related to the section.Side comments are related to the paragraph, therefore they usually appear right or below the text of the paragraph.

A side comment should be inserted within the paragraph of a section, it will appear at the right of the paragraph and vertically aligned with it, or just below the paragraph on smaller screens.

<section>
  <h1>...</h1>
  <p>
    ...
    <small>...<img src="...">...</small>
    ...
  </p>
</section>

Code snippet of a side comment.

Side comments may also contain pictures, added by means of the <img> element.

Images and videos

Images and videos are displayed using the <img> and <video> elements. If a caption is needed, wrap images and videos within the <figure> element and use the <figcaption> element for the caption, as shown in the code snippet below. The <figcaption> element can contain a heading and one or more paragraphs.

Artwork based on Perlin noise, written in GLSL.

<section>
  <h1>...</h1>
  <p>...</p>
  <figure>
    <img src="image.jpg">
    <figcaption>
      <h1>...</h1>
      <p>...</p>
    </figcaption>
  </figure>
  <p>...</p>
</section>

Code snippet of an image, with a descriptive caption.

The <figure> element may be avoided if there is no need for a caption, in such a case the <img> element is a child of the <section> element. The default width of images is 600px, equals to the default width of text paragraph and code snippets. Authors can use inline style declarations to customise the width, as described in section Customisations.

Videos

Exactly the same HTML code snippet is used for displaying videos, with the obvious difference of using the <video> element in place of the <img> element, as shown below.

<section>
  <h1>...</h1>
  <p>...</p>
  <figure>
    <video controls muted src="video.mp4"></video>
    <figcaption>
      <h1>...</h1>
      <p>...</p>
    </figcaption>
  </figure>
  <p>...</p>
</section>

Code snippet of a video with a caption.

As with images, videos have a default width of 600 pixels, customisable with inline declarations as described in section Customisations.

Quotations

This section shows how to add quotations from another source into your document. The <blockquote> element can be inserted in a section within other paragraphs and may contain one or more paragraphs as well.

Content inside a blockquote must be quoted from another source, whose address, if it has one, may be cited in the cite attribute.

HTML Living Standard 
<section>
  <h1>...</h1>
  <p>...</p>
  <blockquote cite="https://...">
    <p>...</p>
  </blockquote>
  <cite>...</cite>
  <p>...</p>
</section>

Code snippet of a quotation from another source.

If appropriate, use the cite attribute for adding a URL of the quotation source and the <cite> element for the text representation.

Highlights

The repetition of some content from the same source is used for the purposes of enticing readers or highlighting key topics. You can repeat a passage or an entire paragraph using the <aside> element inside a section.

<section>
  <h1>...</h1>
  <p>...</p>
  <aside>
    <p>...</p>
  </aside>
  <p>...</p>
</section>

Code snippet of an highlight.

Highlights are styled with a font bigger than the surrounding text.

Tables

As well as with images and videos, tables are displayed within the <figure> element, with an optional caption. Tables are useful for displaying tabular data with few or several columns, if the table is bigger than the window width the hidden part is visible through mouse scrolling.

Tag Meaning Description
<em> emphasis Use it for adding emphasis to a word, compared to surrounding text. Example: "We had to do something about it."
<strong> importance Use it to mark text that has greater importance than surrounding text. Example: "Warning! This is very dangerous."
<mark> relevance Use it to denote content which has a degree of relevance, for example highlighting search results or code fragments.

We take the opportunity of this example to describe the semantic meaning of elements <em>, <strong> and <mark>. Examples are taken from the MDN web docs.

<section>
  <h1>...</h1>
  <p>...</p>
  <figure>
    <div>
      <table>
        <thead>
          <tr>
            <th>...</th>
            <th>...</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>...</td>
            <td>...</td>
          </tr>
          <tr>
            <td>...</td>
            <td>...</td>
          </tr>
        </tbody>
      </table>
    </div>
  </figure>
  <p>...</p>
</section>

Code snippet of a table.

The <thead> element defines the head of the table columns, instead, the <tbody> element is used for the table body. Note that, differently from images and videos, there is an extra <div> container wrapping the <table> element. The default width is 600px, authors can use inline style declarations to customise the table width, as described in section Customisations.

Lists

Lists are created with the <ul> and <ol> elements, whereas <li> element is used to represent list items.

  • use the <ol> element for ordered lists

  • use the <ul> element for unordered lists

<section>
  <h1>...</h1>
  <p>...</p>
  <ul>
    <li>
      <p>...</p>
    </li>
    <li>
      <p>...</p>
    </li>
  </ul>
  <p>...</p>
</section>

Code snippet of code list.

Use the <ol> element when the order is meaningful, ordered list are rendered as a numbered list:

  1. first item

  2. second item

Code

Listings of code can be inserted inline inside a paragraph or within element <figure> for multiple lines of code.

<p>...<code>...</code>...</p>

Code snippet of code listings.

Add inline code using the <code> element.

<figure>
  <pre><code>...</code></pre>
</figure>

Wrap the <code> element within the <pre> element to add multiple lines of code.

As with images, videos and tables, the default width is 600px. You can use inline declarations to customise the width, for example setting 100% width with <pre style="width: 100%">. See section Customisations for more details.

Example 1

const f = n => n ? n * f(n - 1) : 1;

Factorial function in Javascript.

The next code snippet shows how to write the factorial function above.

<figure>
  <pre><code>const f = n => n ? n * f(n - 1) : 1;</code></pre>
</figure>

Listing 1

Example 2

This example shows how to obtain the expected indentation with more lines of code. As rule of thumb, paste the code directly within the <pre><code>...</code></pre> elements.

function factorial (n) {
  return n ? n * factorial(n - 1) : 1;
}
<figure>
  <pre><code>function factorial (n) {
  return n ? n * factorial(n - 1) : 1;
}</code></pre>
</figure>

Example 3

A special treatment is necessary for HTML code because it needs to be escaped: use string &lt; for < and string &gt; for >.

<figure>
  <pre><code>&lt;figure&gt;
  &lt;pre&gt;&lt;code&gt;const f = n => n ? n * f(n - 1) : 1;&lt;/code&gt;&lt;/pre&gt;
&lt;/figure&gt;</code></pre>
</figure>

Snippet used for the HTML code of listing 1.

Highlight code

You can highlight code in two different ways: inline or full lines.

<figure>
  <pre><code>...<mark>...</mark>...</code></pre>
</figure>

Highlight a portion of a line.

Wrap the relevant code within the <mark> element.

Instead, highlight one or more lines of code wrapping the full line within the <mark> element, the next snippet shows an example.

<figure>
  <pre><code>...</code>
<mark><code>...</code></mark>
<code>...</code></pre>
</figure>

Highlight full lines of code.

Note that, within the <pre> element, indentation spaces and new lines deserve special attention in order to represent the right code formatting.

Math formulas

Math typesetting is not supported by default. We suggest using KaTeX, a popular JavaScript library for TeX math rendering on the web. To get KaTex working, copy and paste the next code within the <head> element (see section Getting Started).

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.css" integrity="sha384-D+9gmBxUQogRLqvARvNLmA9hS2x//eK1FhVb9PiU86gmcrBrJAQT8okdJ4LMp2uv" crossorigin="anonymous">
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/katex.min.js" integrity="sha384-483A6DwYfKeDa0Q52fJmxFXkcPCFfnXMoXblOkJ4JcA8zATN6Tm78UNL72AKk+0O" crossorigin="anonymous"></script>
<script defer src="https://cdn.jsdelivr.net/npm/katex@0.10.0-rc.1/dist/contrib/auto-render.min.js" integrity="sha384-yACMu8JWxKzSp/C1YV86pzGiQ/l1YUfE8oPuahJQxzehAjEt2GiQuy/BIvl9KyeF" crossorigin="anonymous" onload="renderMathInElement(document.body,{delimiters: [{left: '$$', right: '$$', display: true},{left: '$', right: '$', display: false}]});"></script>

Example 1

You can insert mathematics inline on a paragraph, like the famous equivalence between energy and inertial mass $E = mc^2$, surrounding the mathematical formula with symbols $...$, as presented below.

<p>... $E = mc^2$ ...</p>

Inline formula.

Example 2

Having your formula in a new line is easy as well, just use $$...$$ instead of $...$.

$$G_{\mu\nu} + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4}T_{\mu\nu}$$Einstein field equations [1], expressed for the first time 8 years later the the happiest thought of my life [2].

<p>
  ...
  $$G_{\mu\nu} + \Lambda g_{\mu\nu} = \frac{8\pi G}{c^4}T_{\mu\nu}$$
  ...
</p>

Example 3

KaTeX supports a wide list of TeX functions. For example, for the representation of the following system of equations, we make use of the \begin{array} environment.

$$\begin{array}{rcl} \nabla \cdot \mathbf{E} & = & 0 \\\\ \nabla \cdot \mathbf{B} & = & 0 \\\\ \nabla \times \mathbf{E} & = & - \displaystyle\frac{1}{c} \displaystyle\frac{\partial \mathbf{B}}{\partial t} \\\\ \nabla \times \mathbf{B} & = & \displaystyle\frac{1}{c} \displaystyle\frac{\partial \mathbf{E}}{\partial t} \end{array}$$

Maxwell's equations in vacuum.

The equations can be reduced to the standard wave equation $$ \frac{1}{c^2} \frac{\partial^2 \mathbf{F}}{\partial^2 t} - \nabla^2 \mathbf{F} = 0 $$ providing the theoretical background for the electromagnetic waves [3]. 

<figure>
  <p>
    $$\begin{array}{rcl}
      \nabla \cdot \mathbf{E} & = & 0 \\\\
      \nabla \cdot \mathbf{B} & = & 0 \\\\
      \nabla \times \mathbf{E} & = & - \displaystyle\frac{1}{c} \displaystyle\frac{\partial \mathbf{B}}{\partial t} \\\\
      \nabla \times \mathbf{B} & = & \displaystyle\frac{1}{c} \displaystyle\frac{\partial \mathbf{E}}{\partial t}
    \end{array}$$
  </p>
</figure>

Use TeX functions for more sophisticated math typesetting. Use the <figure> element if a caption is needed. The default width of the <p> element within the <figure> element is 600px. Authors can use inline style declarations to customise the width for larger formulas, as described in section Customisations.

Customisations

Rapido focuses on semantic HTML, providing a default style for a variety of HTML elements. Being CSS classes out of scope, authors looking for a different style must opt for a customisation.Rapido does not expose CSS classes. This design choice makes Rapido easier to use and, due to how specificity works, easier to extend with custom CSS classes.

You may change the default CSS rules or write new rules that have precedence over the default ones. As usual, this is possible both with inline declarations and stylesheets. The following examples show some common customisations. 

<head>
  ...
  <style>
    article.rapido {
      font-family: "Helvetica Neue";
    }
    article.rapido code {
      font-family: "Iosevka";
    }
  </style>
</head>

Font families.

You can easily change the default font families, both for code and normal text.

<head>
  ...
  <style>
    article.rapido code {
      color: rgba(0, 0, 255, 1);
    }
    article.rapido pre > mark > code {
      border-left: 2px solid rgba(0, 0, 255, 1);
      background: rgba(0, 0, 255, 0.05);
    }
    article.rapido mark {
      background: rgba(0, 0, 255, 0.1);
    }
  </style>
</head>

Font colour on code snippets.

The default colour is blue, authors are encouraged to choose the colour that better adapts to the pre-existing style if any.

<figure>
  <img src="..." style="width: 100%">
  ...
</figure>

Full-width images, videos, tables and code snippets.

The default width is 600 pixels, you can assign to an image a bigger or smaller width than the default one. Full width equals to 944 pixels.

<head>
  ...
  <style>
    .rapido .full-width {
      width: 100%;
    }
  </style>
</head>

Full-width images can be obtained also defining an apposite CSS class, which can be used with <img src="..." class="full-width">. On the same way it can be used with videos (<video>), code snippets (<pre>) and tables (<div>).