Style Guide

HTML5 Rocks
Updated: 2013-11-13

Article wide concepts

New feature warning

For experimental features, include the warning.html text at the top of your content:

{% include "warning.html" %}

This article discusses APIs that are not yet fully standardized and still in flux. Be cautious when using experimental APIs in your own projects.

Adding browser support to the article

Articles can indicate if the user's browser does not support the feature discussed in the article by including an {% block iscompatible %} at the top of the file:

{% block iscompatible %}
  return 'register' in document;
{% endblock %}

The content of the {% block iscompatible %} block should be a JS expression that returns a boolean for the feature detect.

Example: the user's browser doesn't support the feature

Translations

If you provide a translation you can add the translator with {% block translator %} around code that looks this:

<div class="translator">
  <strong>Translator:</strong> <a href="#">Person Name</a>
</div>

Related reading

There are sometimes other articles that you want users to read after they're done with the one they're on. To do that add {% block relatedreading %} around code that looks this:

<aside class="panel">
  <h2>Related reading</h2>
  <ul>
    <li><a href="#">Some article title</a></li>
    <li><a href="#">Some article title</a></li>
    <li><a href="#">Some article title</a></li>
  </ul>
</aside>

Styling features

Keyboard actions

To show keyboard actions, use <kbd> or the kbd class:
<kbd>Ctrl</kbd>+<span class="kbd">Shift</span>+<kbd>J</kbd> (or <kbd>Cmd</kbd>+<kbd>Opt</kbd>+<kbd>J</kbd>)
Ctrl+Shift+J (or Cmd+Opt+J)

Tips & notices

Call out important tips/callouts by adding the notice class on <p>:

<p class="notice"><b>Note:</b> this is a tip you all should know.</p>

Note: this is a tip you all should know.

You can additionally super charge your tips with a label with the fact and tip classes:

<p class="notice tip">This is a tip to remember!</p>
<p class="notice fact">It's a fact Jack.</p>

This is a tip to remember!

It's a fact Jack.

Quotes

Use <blockquote>:

<blockquote>
  A wise person knows wisdom from folly; truth from lies.
</blockquote>
A wise person knows wisdom from folly; truth from lies.

You can also add citations with the <cite> element.

<blockquote>
  A wise person knows wisdom from folly; truth from lies.
  <cite>T. Thinker</cite>
</blockquote>
A wise person knows wisdom from folly; truth from lies T. Thinker

Talking head

To add your mug to the mix, add the talkinghead class to the blockquote and add in a style to adjust the generated content's background-image and positioning:

<style>
.talkinghead:before {
  background-image: url(/static/images/profiles/75/ericbidelman.75.png);
  background-position: 0px 0px !important;
}
</style>

<blockquote class="commentary talkinghead">Listen to my words of wisdom!</blockquote>
Listen to my words of wisdom!

Figures / screenshots

Images within a <figure> are set to max-width: 100% and centered in the article body:

<figure>
  <img src="screenshot.png">
  <figcaption>Screenshot of amazing things</figcaption>
</figure>

You can add a class of bordered if you want a thin gray outline to be added to the image.

<figure>
  <img src="screenshot.png" class="bordered">
  <figcaption>Screenshot of amazing things</figcaption>
</figure>

Code

Snippets

Inline code snippets in paragraph should be put in a <code> element for easier reading.

<p>Some text with an inline <code>navigator.vibrate(...);</code></p>

Blocks

Larger blocks of code should be wrapped in <pre class="prettyprint">:

<pre class="prettyprint">
function myAwesomeFunc() {
  ...
}
</pre>

CSS vendor prefixes

We have a custom Django mixin tag to handle CSS vendor prefixes. The tag renders only the unprefixed property and shows a tooltip when hovering over the property to shows the rest. In this way, we prevent users from directly copying stale code snippets from an article.

To use the mixin tag, ensure it is loaded at the top of your article:

{% load mixin from templatefilters %}
Then, use it inside a code block like so:
<pre class="prettyprint">
<style>
.grayscale {
  {% mixin filter: grayscale(1); %}
}
.promotelayer {
  {% mixin transform: rotateZ(0); %}
}
.gradient {
  background-image: {% mixin linear-gradient(...); %}
}
</style>
</pre>
<style>
.grayscale {
  +filter: grayscale(1);
}
.promotelayer {
  +transform: rotateZ(0);
}
.gradient {
  background-image: +linear-gradient (...); ;
}
</style>