Semantic HTML - adaptlearning/adapt-contrib-vanilla GitHub Wiki

Semantic HTML

It's important to ensure that the HTML used in Adapt is semantically correct to ensure the content is accessible to as many users as possible.

Indeed, W3 state that "Using semantic markup to mark emphasized or special text also provides structure to the document. User agents can then make the structure perceivable to the user, for example using a different visual presentation for different types of structures or by using a different voice or pitch in an auditory presentation."

Common mistakes

To help with the often murky subject, a brief explanation of some common HTML element mistakes has been detailed below:

strong vs b

Often used interchangeably, there is a small but clear difference between the two semantically. A <strong> element is used "...for content that is of greater importance..." whilst the <b> element is used " draw attention to text without indicating that it's more important."

Put simply, use the <strong> element when content is required to convey importance, seriousness, or urgency whilst a <b> element should be used to highlight text without adding importance.

However, a <b> element should not be used for decoration, instead bolding text visually should be done through CSS.

em vs i

In a similar vein to the <strong> element, the <em> element is designed to add further context to the text. The <em> element "... is for words that have a stressed emphasis compared to surrounding text, which is often limited to a word or words of a sentence and affects the meaning of the sentence itself."

In comparison, the <i> element is "...for text that is set off from the normal prose for readability reasons." Examples include the representation of "...a foreign word, fictional character thoughts, or when the text refers to the definition of a word instead of representing its semantic meaning."

The <i> element should also not be used for decoration, instead italicising text visually should be done through CSS.


There are a number of HTML elements available to support semantically correct quotation but it's important to choose the right elements for the content provided.

The <blockquote> is likely to be one of the most common HTML quote elements to be used and "...indicates that the enclosed text is an extended quotation". It should be used when quoting longer pieces of text and supports the use of other HTML elements within such as <p>, <h1>, and <ul>.

  <p>Pellentesque vehicula odio sed aliquam porta. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas.</p>
  <p>Morbi bibendum metus sit amet diam feugiat, vel sollicitudi est rhoncus. In ultricies turpis at lacus fermentum aliquet. In hac habitasse platea dictumst.</p>
Screenshot 2022-11-30 at 12 28 16

The <q> element provides wrapping quote marks to the text within and is "...intended for short [inline] quotations that don't require paragraph breaks...".

<p>In aliquam <q>vehicula mauris et hendrerit, nulla sed <q>dui dictum</q>, faucibus ipsum sed</q>, dictum diam.</p>
Screenshot 2022-11-30 at 12 28 39

The <cite> element is used in conjunction with the <blockquote> and <q> to "...describe a reference to a cited creative work, and must include the title of that work." It should not be used to contain quoted text but rather to attribute the quote to the piece of work.

It should be noted that there is disagreement between W3 and WHATWG as to whether the <cite> element may include the authors name. For avoidance of doubt, the Vanilla theme is set up to support quotation using the <figure> element and <figcaption> for attribution.

<p>Donec viverra vehicula luctus. <cite>Mauris eu</cite> convallis ligula. Sed tempor feugiat ipsum id maximus.</p>
Screenshot 2022-11-30 at 12 35 34

The <figure> element is not exclusively used for quotes, instead it "...represents self-contained content...". This is to say that everything within should be considered a singular piece of content.

The <figcaption> element provides "A caption [that] can be associated with the <figure> element...". It is for use exclusively within the <figure> element and must be either the first or last element within its parent.

These two elements can be combined to create a semantically correct, browser styled, self-contained quote with either an author and / or a creative work attribution.

    <p>Nam quis eros pretium, commodo quam vel, posuere velit. Cras consectetur pellentesque lacus. In arcu nibh, volutpat eget lacus ut, ultricies dapibus arcu. Nulla ut ante ut mauris lobortis volutpat vitae vitae erat. Curabitur egestas viverra lorem id molestie. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.</p>
  <figcaption><cite>Lorem Ipsum</cite> by Joe Bloggs</figcaption>
Screenshot 2022-11-30 at 12 38 29

figure custom class

To apply the pre-built Vanilla quote styling, add the custom class figure-quote to the <figure> element.

<figure class='figure-quote'>
Screenshot 2022-11-30 at 12 43 36

Similarly to <figure>, the <aside> element isn't strictly used for quotes but instead it "...represents a portion of a document whose content is only indirectly related to the document's main content". As such, the element provides an ideal base from which to build a semantically correct pull quote.

<aside class="aside-pull-quote" role="doc-pullquote presentation" aria-hidden="true">
  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam feugiat faucibus eros, sed porttitor velit sollicitudin id.

aside custom class

To apply the pre-defined Vanilla pull quote styling, add the custom class aside-pull-quote to the <aside> element. See the screenshot below for the standard visual display.

aside role and aria attribute

The doc-pullquote aria role "is typically used on blockquote, aside and div elements when the quote is duplicated in a separate element. The addition of an aria-hidden attribute in these cases prevents the content from being read again to users of assistive technologies.

Note: the ARIA 1.1 specification currently advises adding the backup role of presentation until support for none becomes more prevalent. As doc-pullquote inherits from none, the same advice applies for this role." reference

Screenshot 2022-11-30 at 14 25 10
⚠️ ** Fallback** ⚠️