-
Notifications
You must be signed in to change notification settings - Fork 20
Code standards: HTML
The status of this document is currently Request for Comments.
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.
Use HTML5. Always declare the correct doctype as the very first element in the document. Doctype declarations MUST be written in UPPERCASE.
<!DOCTYPE html>Always declare the correct ISO 639-1 language (and reading direction, if applicable) for the document. Standardize on en-US for documents in English.
<html lang="en-US"> ... </html>Write all tags and attributes in lowercase. Write attribute values in lowercase where possible.
Use double quotes around attribute values in all cases, and use the HTML entity for quotes (") when the attribute value itself contains a double quote.
<link type="text/css" rel="stylesheet" href="https://codidact.org/assets/product.css" />Always close all void elements. While this is not required by HTML5, it is allowed, and helps avoid confusion from programmers who are less used to the rule. Additionally, it might be beneficial to anyone using an XML parser on our page contents (not that we recommend it).
A space MUST appear between the last character in the HTML tag and the trailing slash.
<!-- acceptable: -->
<br />
<img src="..." alt="..." />
<!-- forbidden: -->
<br/>
<img src="..." alt="...">When referencing external resources (including those local to the domain), do not omit the protocol. Always use HTTPS access to resources if possible.
Prefer retrieving resources by canonical URIs when possible, i.e. those that do not redirect upon request. Check with a command-line tool or a service such as apitester.com to be sure.
<script type="application/javascript" src="https://codidact.org/assets/product.js"></script>
<!-- note - not using 'www.codidact.org', as this one redirects (HTTP 301) to the non-www URI -->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>Prefer semantic elements where possible: use <main> over <div class="main">, or <footer> over <div class="footer">.
Do not write lines longer than 140 characters. Do not rely on editor word-wrap to wrap lines for you.
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" />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" />Ensure all pages have a title.
<title>Codidact | Questions</title>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." />Reference non-CSS assets first, such as a favicon or rel="canonical" link. Reference CSS assets afterward. 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>Scripts SHOULD be loaded asynchronously or deferred whenever possible.
<!-- from: <https://stackoverflow.com/a/24070373> -->
<script type="text/javascript" src="path/to/script1.js" async></script>
<script type="text/javascript" src="path/to/script2.js" defer></script>
<!-- ES6 - from: <https://stackoverflow.com/a/54482274> -->
<script type="module" src="path/to/script3.js"></script>Non-standard fonts should be added via CSS and SHOULD be hosted locally - i.e. no third-party requests for fonts. This is due to privacy considerations. Exceptions to this rule are to be considered on a case-by-case basis.
Example (in CSS):
@font-face {
font-family: "Source Code Pro";
font-style: normal;
font-weight: 400;
font-display: swap;
src: local("Source Code Pro Regular"), local("SourceCodePro-Regular"), url("/assets/fonts/HI_SiYsKILxRpg3hIP6sJ7fM7PqlPevW.woff2") format("woff2");
unicode-range: U+0000-00FF, U+0131, U+0152-0153, U+02BB-02BC, U+02C6, U+02DA, U+02DC, U+2000-206F, U+2074, U+20AC, U+2122, U+2191, U+2193, U+2212, U+2215, U+FEFF, U+FFFD;
}
.code-block {
font-family: "Source Code Pro", "Consolas", "Lucida Console", monospace, sans-serif;
}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>-
If using
target="_blank"to open links in a new tab, also includerel="noopener noreferrer". -
If a JS-enabled link is necessary (it normally shouldn't - see note below), prefer
href="#"overhref="javascript:void(0)"(and its equivalenthref="javascript:;"). Please do combine this withevent.preventDefault()in order to prevent unwanted scrolling and adding of pointless entries to the user's browsing history.Note: Since the above directive still requires JavaScript to be enabled, the RECOMMENDED first-line approach is to either link to an actual page/resource that performs the same expected action, or use a
<button>element styled as a link instead. The JS-enabled link (<a>) strategy MUST be reserved for the rare cases, if any, where these are not possible - and ideally, they SHOULD be added ("injected") to the page using JavaScript.[1] [2]
- Use a compressed image format or small file size where possible.
- Make use of
<picture>/srcsetwhere possible. - Load images asynchronously where possible.
- Ensure all pages have a level 1 header (
<h1>) that is not the website name. - Pages MUST NOT have more than one
<h1>element. - Use headings in order; style via CSS rather than using a smaller heading level.
- Use specific input types such as
type="email"andtype="number"rather thantype="text"for every field. - Ensure every input has a unique ID.
- Ensure every input has a related
<label>, or if not possible, anaria-labelattribute.
Ensure all pages are navigable using the keyboard only, and all interactive elements and inputs are reachable.
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.