Skip to content
This repository has been archived by the owner on Jul 17, 2020. It is now read-only.

Code standards: HTML

Jump to bottom
ArtOfCode edited this page Nov 14, 2019 · 14 revisions

The following is our style guide for writing HTML. All HTML contributions MUST adhere to this document unless there's a good reason not to; such reasons MUST have a linter ignore applied to them, and SHOULD be documented using a comment above the relevant code.

1. Document

1.1 HTML Version & Doctype

Use HTML5. Always declare the correct doctype as the very first element in the document. Doctype declarations should be written in UPPERCASE.

<!DOCTYPE html>

1.2 Language

Always declare the correct ISO 639-1 language (and reading direction, if applicable) for the document. Standardise on en-US for documents in English.

<html lang="en-US"> ... </html>

1.3 Casing

Write all tags and attributes in lowercase. Write attribute values in lowercase where possible. Use double quotes around attribute values, except where the value contains a double quote.

<link type="text/css" rel="stylesheet" href="https://codidact.org/assets/product.css" />

1.4 Void elements

Always close all void elements. Do not rely on browser HTML parsers or self-closing elements to close elements for you.

<br/> <!-- OR (both are acceptable) --> <br />
<p>This is a paragraph.</p>

1.5 External resources

When referencing external resources (including those local to the domain), do not omit the protocol. Always use HTTPS access to resources if possible.

<script type="application/javascript" src="https://codidact.org/assets/product.js"></script>

1.6 Indentation

Use four spaces per level of indentation. Do not use tab stops.

<body>
    <div class="modal modal--urgent"> ... </div>
</body>

On element declarations whose attributes span over more than one line, align subsequent lines with the first attribute on the first line.

<div id="question-select-modal" class="modal modal--urgent js-question-select" title="Select your question here."
     data-source-question="122349" data-merge-id="99182">
    ...
</div>

1.7 Semantic elements

Prefer semantic elements where possible: use <main> over <div class="main">, or <footer> over <div class="footer">.

1.8 Line length

Do not write lines longer than 150 characters. Do not rely on editor word-wrap to wrap lines for you.

2. Head

2.1 Encoding

Use UTF8 encoding, without BOM. Ensure your editor is set to use UTF8 w/o BOM. Always declare the document encoding as the first element in the <head> section.

<meta charset="utf-8" />

2.2 Viewport

Correctly declare the viewport. Applications SHOULD be responsive, but if they are not, do not declare the viewport as mobile-friendly. Generally, do not set user-scalable=no.

<!-- For responsive applications: -->
<meta name="viewport" content="width=device-width, initial-scale=1" />
<!-- For non-responsive applications (adjust width as necessary): -->
<meta name="viewport" content="width=1024" />

2.3 Title

Ensure all pages have a title.

<title>Codidact | Questions</title>

2.4 Description

Ensure all pages have a declared meta description, unless the page is not intended for public consumption.

<meta name="description" content="Questions on Codidact, a Q&A-style knowledge-sharing community." />

2.5 Links and scripts

Reference non-CSS assets first, such as a favicon or rel="canonical" link. Reference CSS assets afterwards. Reference scripts last. Correctly declare the content-type on every asset. Generally, reference external (off-domain) assets before on-domain assets.

<link rel="canonical" href="https://codidact.org/questions/8812372/why-is-my-query-not-working" />
<link rel="stylesheet" type="text/css" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" />
<link rel="stylesheet" type="text/css" href="https://codidact.org/assets/product.css" />
<script type="application/javascript" src="https://codidact.org/assets/product.js"></script>

3. Body

3.1 JavaScript references

When adding an ID or class to reference an element from JavaScript, prefix the value with js-.

<div class="modal modal--urgent js-question-select"> ... </div>

3.2 <a>

  • If using target="_blank" to open links in a new tab, also include rel="noopener noreferrer".
  • Prefer href="#" over href="javascript:void(0)" for JS-enabled links; use event.preventDefault() in JavaScript.

3.3 <img>

  • Use a compressed image format or small file size where possible.
  • Make use of <picture>/srcset where possible.
  • Load images asynchronously where possible.

3.4 <h1-6>

  • Ensure all pages have a <h1> that is not the website name.
  • Use headings in order; style via CSS rather than using a smaller heading level.

3.5 <input>

  • Use specific input types such as type="email" and type="number" rather than type="text" for every field.
  • Ensure every input has a unique ID.
  • Ensure every input has a related <label>, or if not possible, an aria-label attribute.

3.6 Keyboard navigation

Ensure all pages are navigable using the keyboard only, and all interactive elements and inputs are reachable.

3.7 Progressive enhancement

Make sure major features (i.e. navigation, search, etc.) are usable without JavaScript enabled. Some feature degradation is acceptable, but should be kept to a minimum. Ensure a correct <noscript> message is shown to explain why features are unavailable.

Clone this wiki locally