W3C

HTML 5.3

W3C Working Draft,

4.2. Document metadata

4.2.1. The head element

Categories:
None.
Contexts in which this element can be used:
As the first element in an html element.
Content model:
If the document is an iframe srcdoc document or if title information is available from a higher-level protocol: Zero or more elements of metadata content, of which no more than one is a title element and no more than one is a base element.
Otherwise: One or more elements of metadata content, of which exactly one is a title element and no more than one is a base element.
Tag omission in text/html:
A head element’s start tag may be omitted if the element is empty, or if the first thing inside the head element is an element.
A head element’s end tag may be omitted if the head element is not immediately followed by a space character or a comment.
Content attributes:
Global attributes
Allowed ARIA role attribute values:
None
Allowed ARIA state and property attributes:
None
DOM interface:
interface HTMLHeadElement : HTMLElement {};

The head element represents a collection of metadata for the Document.

The collection of metadata in a head element can be large or small. Here is an example of a very short one:
<!doctype html>
<html lang="en">
  <head>
    <title>A document with a short head</title>
  </head>
  <body>
    ...

Here is an example of a longer one:

<!DOCTYPE HTML>
  <HTML lang="en">
  <HEAD>
    <META CHARSET="UTF-8">
    <BASE HREF="https://www.example.com/">
    <TITLE>An application with a long head</TITLE>
    <LINK REL="STYLESHEET" HREF="default.css">
    <LINK REL="STYLESHEET ALTERNATE" HREF="big.css" TITLE="Big Text">
    <SCRIPT SRC="support.js"></SCRIPT>
    <META NAME="APPLICATION-NAME" CONTENT="Long headed application">
  </HEAD>
  <BODY>
    ...

The title element is a required child in most situations, but when a higher-level protocol provides title information, e.g., in the Subject line of an e-mail when HTML is used as an e-mail authoring format, the title element can be omitted.

It is recommended to keep the usage of attributes and their values defined on the head element to a minimum to allow for proper detection of the character encoding declaration within the first 1024 bytes.

4.2.2. The title element

Categories:
Metadata content.
Contexts in which this element can be used:
In a head element containing no other title elements.
Content model:
Text that is not inter-element white space.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
Allowed ARIA role attribute values:
None
Allowed ARIA state and property attributes:
None
DOM interface:
interface HTMLTitleElement : HTMLElement {
  attribute DOMString text;
};

The title element represents the document’s title or name. Authors should use titles that identify their documents even when they are used out of context, for example in a user’s history or bookmarks, or in search results. The document’s title is often different from its first heading, since the first heading does not have to stand alone when taken out of context.

There must be no more than one title element per document.

If it’s reasonable for the Document to have no title, then the title element is probably not required. See the head element’s content model for a description of when the element is required.

title . text [ = value ]
Returns the child text content of the element.

Can be set, to replace the element’s children with the given value.

The IDL attribute text must return the child text content of the title element. On setting, it must act the same way as the textContent IDL attribute.

Here are some examples of appropriate titles, contrasted with the top-level headings that might be used on those same pages.
<title>Introduction to The Mating Rituals of Bees</title>
...
<h1>Introduction</h1>
<p>This companion guide to the highly successful
<cite>Introduction to Medieval Bee-Keeping</cite> book is...

The next page might be a part of the same site. Note how the title describes the subject matter unambiguously, while the first heading assumes the reader knows what the context is and therefore won’t wonder if the dances are Salsa or Waltz:

<title>Dances used during bee mating rituals</title>
...
<h2>The Dances</h2>

The string to use as the document’s title is given by the document.title IDL attribute.

User agents should use the document’s title when referring to the document in their user interface. When the contents of a title element are used in this way, the directionality of that title element should be used to set the directionality of the document’s title in the user interface.

4.2.3. The base element

Categories:
Metadata content.
Contexts in which this element can be used:
In a head element containing no other base elements.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
hrefDocument base URL
target — Default browsing context for hyperlink navigation and §4.10.21 Form submission
Allowed ARIA role attribute values:
None
Allowed ARIA state and property attributes:
None
DOM interface:
interface HTMLBaseElement : HTMLElement {
  attribute DOMString href;
  attribute DOMString target;
};

The base element allows authors to specify the document base URL for the purposes of §2.5.2 Parsing URLs, and the name of the default browsing context for the purposes of following hyperlinks. The element does not represent any content beyond this information.

There must be no more than one base element per document.

A base element must have either an href attribute, a target attribute, or both.

The href content attribute, if specified, must contain a valid URL potentially surrounded by spaces.

A base element, if it has an href attribute, must come before any other elements in the tree that have attributes defined as taking URLs, except the html element (its manifest attribute isn’t affected by base elements).

If there are multiple base elements with href attributes, all but the first are ignored.

The target attribute, if specified, must contain a valid browsing context name or keyword, which specifies which browsing context is to be used as the default when hyperlinks and forms in the Document cause navigation.

A base element, if it has a target attribute, must come before any elements in the tree that represent hyperlinks.

If there are multiple base elements with target attributes, all but the first are ignored.

A base element that is the first base element with an href content attribute in a document tree has a frozen base URL. The frozen base URL must be immediately set for an element whenever any of the following situations occur:

To set the frozen base URL, for an element element:

  1. Let document be element’s node document.

  2. Let urlRecord be the result of parsing the value of element’s href content attribute with document’s fallback base URL, and document’s character encoding. (Thus the base element isn’t affected by itself.)

  3. Set elements’s frozen base URL to document’s fallback base URL, if urlRecord is failure or running Is base allowed for Document? on the resulting URL record and document returns "Blocked", and to urlRecord otherwise.

The href IDL attribute, on getting, must return the result of running the following algorithm:

  1. Let document be element’s node document.

  2. Let url be the value of the href attribute of the base element, if it has one, and the empty string otherwise.

  3. Let urlRecord be the result of parsing url with document’s fallback base url, and document’s character encoding. (Thus, the base element isn’t affected by other base elements or itself).

  4. If urlRecord is failure, return url.

  5. Return the serialization of urlRecord.

The href IDL attribute, on setting, must set the href content attribute to the given new value.

The target IDL attribute must reflect the content attribute of the same name.

In this example, a base element is used to set the document base URL:
<!DOCTYPE html>
<html lang="en">
  <head>
    <title>This is an example for the &lt;base&gt; element</title>
    <base href="https://www.example.com/news/index.html">
  </head>
  <body>
    <p>Visit the <a href="archives.html">archives</a>.</p>
  </body>
</html>

The link in the above example would be a link to "https://www.example.com/news/archives.html".

Categories:
Metadata content.
If the element is allowed in the body: flow content.
If the element is allowed in the body: phrasing content.
Contexts in which this element can be used:
Where metadata content is expected.
In a noscript element that is a child of a head element.
If the element is allowed in the body: where phrasing content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
href — Address of the hyperlink
crossorigin — How the element handles crossorigin requests
rel — Relationship of this document (or subsection/topic) to the destination resource
revReverse link relationship of the destination resource to this document (or subsection/topic)
media — Applicable media
hreflang — Language of the linked resource
type — Hint for the type of the referenced resource
referrerpolicy - Referrer policy for fetches initiated by the element
sizes — Sizes of the icons (for rel="icon")
as — Destination for a preload request (for rel="preload")
Also, the title attribute has special semantics on this element: Title of the link; alternative style sheet set name.
Allowed ARIA role attribute values:
link (default - do not set)
Allowed ARIA state and property attributes:
None
DOM interface:
interface HTMLLinkElement : HTMLElement {
   [CEReactions] attribute USVString href;
   [CEReactions] attribute DOMString? crossOrigin;
   [CEReactions] attribute DOMString rel;
   [CEReactions] attribute DOMString rev;
   [CEReactions] attribute DOMString as;  // (default "")
   [CEReactions, SameObject, PutForwards=value] readonly attribute DOMTokenList relList;
   [CEReactions] attribute DOMString media;
   [CEReactions] attribute DOMString hreflang;
   [CEReactions] attribute DOMString type;
   [CEReactions, SameObject, PutForwards=value] readonly attribute DOMTokenList sizes;
   [CEReactions] attribute DOMString referrerPolicy;
};
 HTMLLinkElement implements LinkStyle;

The link element allows authors to link their document to other resources.

The destination of the link(s) is given by the href attribute, which must be present and must contain a valid non-empty URL potentially surrounded by spaces. If the href attribute is absent, then the element does not define a link.

The crossorigin attribute is a CORS settings attribute. It is intended for use with external resource links.

The types of link indicated (the relationships) are given by the value of the rel attribute, which, if present, must have a value that is a set of space-separated tokens. The allowed keywords and their meanings are defined in a later section. If the rel attribute is absent, has no keywords, or if none of the keywords used are allowed according to the definitions in this specification, then the element does not create any links.

rel's supported tokens are the keywords defined in HTML link types which are allowed on link elements, impact the processing model, and are supported by the user agent. The possible supported tokens are alternate, dns-prefetch, icon, next, pingback, preconnect, prefetch, preload, prerender, search, serviceworker, and stylesheet. rel's supported tokens must only include the tokens from this list that the user agent implements the processing model for.

A link element must have a rel attribute.

If a link element has a rel attribute that contains only keywords that are body-ok, then the element is said to be allowed in the body. This means that the element can be used where phrasing content is expected.

Two categories of links can be created using the link element: Links to external resources and hyperlinks. The link types section defines whether a particular link type is an external resource or a hyperlink. One link element can create multiple links (of which some might be external resource links and some might be hyperlinks); exactly which and how many links are created depends on the keywords given in the rel attribute. User agents must process the links on a per-link basis, not a per-element basis.

Each link created for a link element is handled separately. For instance, if there are two link elements with rel="stylesheet", they each count as a separate external resource, and each is affected by its own attributes independently. Similarly, if a single link element has a rel attribute with the value next stylesheet, it creates both a hyperlink (for the next keyword) and an external resource link (for the stylesheet keyword), and they are affected by other attributes (such as media or title) differently.

For example, the following link element creates two hyperlinks (to the same page):
<link rel="author license" href="/about">

The two links created by this element are one whose semantic is that the target page has information about the current page’s author, and one whose semantic is that the target page has information regarding the license under which the current page is provided.

Hyperlinks created with the link element and its rel attribute apply to the whole document. This contrasts with the rel attribute of a and area elements, which indicates the type of a link whose context is given by the link’s location within the document.

The exact behavior for links to external resources depends on the exact relationship, as defined for the relevant link type. Some of the attributes control whether or not the external resource is to be applied (as defined below).

The media attribute says which media the resource applies to. The value must be a valid media query list.

The integrity attribute represents the integrity metadata for requests which this element is responsible for. The value is text. The attribute must not be specified on link elements that do not have a rel attribute that contains the stylesheet keyword. [SRI]

The hreflang attribute on the link element has the same semantics as the hreflang attribute on the a element.

The type attribute gives the MIME type of the linked resource. It is purely advisory. The value must be a valid mime type.

For external resource links, the type attribute is used as a hint to user agents so that they can avoid fetching resources they do not support.

The referrerpolicy attribute is a referrer policy attribute. It is intended for use with external resource links, where it helps set the referrer policy used when obtaining the external resource. [REFERRERPOLICY].

The title attribute gives the title of the link. With one exception, it is purely advisory. The value is text. The exception is for style sheet links, where the title attribute defines alternative style sheet sets.

The title attribute on link elements differs from the global title attribute of most other elements in that a link without a title does not inherit the title of the parent element: it merely has no title.


The sizes attribute gives the sizes of icons for visual media. Its value, if present, is merely advisory. User agents may use the value to decide which icon(s) to use if multiple icons are available. If specified, the attribute must have a value that is an unordered set of unique space-separated tokens which are ASCII case-insensitive. Each value must be either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The attribute must not be specified on link elements that do not have a rel attribute that specifies the icon keyword or the apple-touch-icon keyword.

The apple-touch-icon keyword is a registered extension to the predefined set of link types, but user agents are not required to support it in any way.


The as attribute specifies the potential destination for a preload request for the resource given by the href attribute. It is an enumerated attribute. Each potential destination is a keyword for this attribute, mapping to a state of the same name. The attribute must be specified on link elements that have a rel attribute that contains the preload keyword, but must not be specified on link elements which do not. The processing model for how the as attribute is used is given in the steps to obtain the resource.

The attribute does not have a missing value default or invalid value default, meaning that invalid or missing values for the attribute map to no state. This is accounted for in the processing model.


The IDL attributes href, hreflang, integrity, media, rel, rev, sizes, and type each must reflect the respective content attributes of the same name.

The crossOrigin IDL attribute must reflect the crossorigin content attribute.

The referrerPolicy IDL attribute must reflect the referrerpolicy content attribute, limited to only known values.

The IDL attribute relList must reflect the rel content attribute.

The as IDL attribute must reflect the as content attribute, limited to only known values.

If the link is a hyperlink then the media attribute is purely advisory, and describes for which media the document in question was designed.

However, if the link is an external resource link, then the media attribute is prescriptive. The user agent must apply the external resource when the media attribute’s value matches the environment and the other relevant conditions apply, and must not apply it otherwise.

The default, if the media attribute is omitted, is "all", meaning that by default links apply to all media.

The external resource might have further restrictions defined within that limit its applicability. For example, a CSS style sheet might have some @media blocks. This specification does not override such further restrictions or requirements.

If type attribute is present, then the user agent must assume that the resource is of the given type (even if that is not a valid mime type, e.g., the empty string). If the attribute is omitted, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type. If the user agent does not support the given MIME type for the given link relationship, then the user agent should not obtain the resource; if the user agent does support the given MIME type for the given link relationship, then the user agent should obtain the resource at the appropriate time as specified for the external resource link’s particular type. If the attribute is omitted, and the external resource link type does not have a default type defined, but the user agent would obtain the resource if the type was known and supported, then the user agent should obtain the resource under the assumption that it will be supported.

User agents must not consider the type attribute authoritative — upon fetching the resource, user agents must not use the type attribute to determine its actual type. Only the actual type (as defined in the next paragraph) is used to determine whether to apply the resource, not the aforementioned assumed type.

If the external resource link type defines rules for processing the resource’s Content-Type metadata, then those rules apply. Otherwise, if the resource is expected to be an image, user agents may apply the image sniffing rules, with the official type being the type determined from the resource’s Content-Type metadata, and use the resulting computed type of the resource as if it was the actual type. Otherwise, if neither of these conditions apply or if the user agent opts not to apply the image sniffing rules, then the user agent must use the resource’s Content-Type metadata to determine the type of the resource. If there is no type metadata, but the external resource link type has a default type defined, then the user agent must assume that the resource is of that type.

The stylesheet link type defines rules for processing the resource’s Content-Type metadata.

Once the user agent has established the type of the resource, the user agent must apply the resource if it is of a supported type and the other relevant conditions apply, and must ignore the resource otherwise.

If a document contains style sheet links labeled as follows:
<link rel="stylesheet" href="A" type="text/plain">
<link rel="stylesheet" href="B" type="text/css">
<link rel="stylesheet" href="C">

...then a compliant user agent that supported only CSS style sheets would fetch the B and C files, and skip the A file (since text/plain is not the MIME type for CSS style sheets).

For files B and C, it would then check the actual types returned by the server. For those that are sent as text/css, it would apply the styles, but for those labeled as text/plain, or any other type, it would not.

If one of the two files was returned without a Content-Type metadata, or with a syntactically incorrect type like Content-Type: "null", then the default type for stylesheet links would kick in. Since that default type is text/css, the style sheet would nonetheless be applied.

For external resources that are represented in the DOM (for example, style sheets), the DOM representation must be made available (modulo cross-origin restrictions) even if the resource is not applied. To obtain the resource, the user agent must run the following steps:

  1. If the href attribute’s value is the empty string, then return.

  2. Parse the URL given by the href attribute, relative to the element’s node document. If that fails, then return. Otherwise, let url be the resulting URL record.

  3. Let corsAttributeState be the current state of the element’s crossorigin content attribute.

  4. Let request be the result of creating a potential-CORS request given url, the empty string, and corsAttributeState.

  5. Set request’s client to the link element’s node document’s Window object’s environment settings object.

  6. Set request’s cryptographic nonce metadata to the current value of the link element’s [[CryptographicNonce]] internal slot.

  7. Set request’s integrity metadata to the current value of the link element’s integrity content attribute.

  8. Set request’s referrer policy to the current state of the link element’s referrerpolicy attribute.

  9. If the rel attribute contains the preload keyword, then:

    1. Let as be the current state of the as attribute.

    2. If as is no state, then return.

    3. Set request’s destination to the result of translating as.

  10. Fetch request.

User agents may opt to only try to obtain such resources when they are needed, instead of pro-actively fetching all the external resources that are not applied.

The semantics of the protocol used (e.g., HTTP) must be followed when fetching external resources. (For example, redirects will be followed and 404 responses will cause the external resource to not be applied.)

Once the attempts to obtain the resource and its critical subresources are complete, the user agent must, if the loads were successful, queue a task to fire an event named load at the link element, or, if the resource or one of its critical subresources failed to completely load for any reason (e.g., DNS error, HTTP 404 response, a connection being prematurely closed, unsupported Content-Type), queue a task to fire an event named error at the link element. Non-network errors in processing the resource or its subresources (e.g., CSS parse errors, PNG decoding errors) are not failures for the purposes of this paragraph.

The task source for these tasks is the DOM manipulation task source.

Unless otherwise specified for a given rel keyword, the element must delay the load event of the element’s node document until all the attempts to obtain the resource and its critical subresources are complete. (Resources that the user agent has not yet attempted to obtain, e.g., because it is waiting for the resource to be needed, do not delay the load event.)

HTTP Link: headers, if supported, must be assumed to come before any links in the document, in the order that they were given in the HTTP message. These headers are distinct from HTML link types, and thus their semantics can be different from same-named HTML types.

Interactive user agents may provide users with a means to follow the hyperlinks created using the link element, somewhere within their user interface. The exact interface is not defined by this specification, but it could include the following information (obtained from the element’s attributes, again as defined below), in some form or another (possibly simplified), for each hyperlink created with each link element in the document:

User agents could also include other information, such as the type of the resource (as given by the type attribute).

The activation behavior of link elements that create hyperlinks is to run the following steps:

  1. If the link element’s node document is not fully active, then abort these steps.

  2. Follow the hyperlink created by thelink element.

4.2.4.6. The LinkStyle interface

The LinkStyle interface is also implemented by this element. [CSSOM]

Here, a set of link elements provide some style sheets:
<!-- a persistent style sheet -->
<link rel="stylesheet" href="default.css">

<!-- the preferred alternate style sheet -->
<link rel="stylesheet" href="green.css" title="Green styles">

<!-- some alternate style sheets -->
<link rel="alternate stylesheet" href="contrast.css" title="High contrast">
<link rel="alternate stylesheet" href="big.css" title="Big fonts">
<link rel="alternate stylesheet" href="wide.css" title="Wide screen">
The following example shows how you can specify versions of the page that use alternative formats, are aimed at other languages, and that are intended for other media:
<link rel=alternate href="/en/html" hreflang=en type=text/html title="English HTML">
<link rel=alternate href="/fr/html" hreflang=fr type=text/html title="French HTML">
<link rel=alternate href="/en/html/print" hreflang=en type=text/html media=print title="English HTML (for printing)">
<link rel=alternate href="/fr/html/print" hreflang=fr type=text/html media=print title="French HTML (for printing)">
<link rel=alternate href="/en/pdf" hreflang=en type=application/pdf title="English PDF">
<link rel=alternate href="/fr/pdf" hreflang=fr type=application/pdf title="French PDF">

4.2.5. The meta element

Categories:
Metadata content.
Contexts in which this element can be used:
If the charset attribute is present, or if the element’s http-equiv attribute is in the encoding declaration state: in a head element.
If the http-equiv attribute is present but not in the encoding declaration state: in a head element.
If the http-equiv attribute is present but not in the encoding declaration state: in a noscript element that is a child of a head element.
If the name attribute is present: where metadata content is expected.
Content model:
Nothing.
Tag omission in text/html:
No end tag.
Content attributes:
Global attributes
name — Metadata name
http-equiv — Pragma directive
content — Value of the element
charsetCharacter encoding declaration
Allowed ARIA role attribute values:
None
Allowed ARIA state and property attributes:
None
DOM interface:
interface HTMLMetaElement : HTMLElement {
  attribute DOMString name;
  attribute DOMString httpEquiv;
  attribute DOMString content;
};

The meta element represents various kinds of metadata that cannot be expressed using the title, base, link, style, and script elements.

The meta element can represent document-level metadata with the name attribute, pragma directives with the http-equiv attribute, and the file’s character encoding declaration when an HTML document is serialized to string form (e.g., for transmission over the network or for disk storage) with the charset attribute.

Exactly one of the name, http-equiv, and charset attributes must be specified.

If either name or http-equiv is specified, then the content attribute must also be specified. Otherwise, it must be omitted.

The charset attribute specifies the character encoding used by the document. This is a character encoding declaration. If the attribute is present in an XML document, its value must be an ASCII case-insensitive match for the string "utf-8" (and the document is therefore forced to use UTF-8 as its encoding).

The charset attribute on the meta element has no effect in XML documents, and is only allowed in order to facilitate migration to and from XHTML.

There must not be more than one meta element with a charset attribute per document.

The content attribute gives the value of the document metadata or pragma directive when the element is used for those purposes. The allowed values depend on the exact context, as described in subsequent sections of this specification.

<meta name="viewport" content="..."> allows authors to define specific viewport characteristics (such as the layout viewport’s width and zoom factor) for their documents. Among these is the ability to prevent or restrict users from being able to zoom, using content values such as user-scalable=no or maximum-scale=1.0. Authors should not suppress or limit the ability of users to resize a document, as this causes accessibility and usability issues.

The following examples illustrate code that should be avoided:
<!-- DO NOT DO THIS -->

<meta name="viewport" content="user-scalable=no">

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0">

There may be specific use cases where preventing users from zooming may be appropriate, such as map applications – where custom zoom functionality is handled via scripting. However, in general this practice should be avoided, and HTML conformance checking tools should display a warning if they encounter these values.

Note that most user agents now allow users to always zoom, regardless of any <meta name="viewport" content="..."> restrictions – either by default, or as a setting/option (which may however not be immediately apparent to users).

If a meta element has a name attribute, it sets document metadata. Document metadata is expressed in terms of name-value pairs, the name attribute on the meta element giving the name, and the content attribute on the same element giving the value. The name specifies what aspect of metadata is being set; valid names and the meaning of their values are described in the following sections. If a meta element has no content attribute, then the value part of the metadata name-value pair is the empty string.

The name and content IDL attributes must reflect the respective content attributes of the same name. The IDL attribute httpEquiv must reflect the content attribute http-equiv.

4.2.5.1. Standard metadata names

This specification defines a few names for the name attribute of the meta element.

Names are case-insensitive, and must be compared in an ASCII case-insensitive manner.

application-name

The value must be a short free-form string giving the name of the Web application that the page represents. If the page is not a Web application, the application-name metadata name must not be used. Translations of the Web application’s name may be given, using the lang attribute to specify the language of each name.

There must not be more than one meta element with a given language and with its name attribute set to the value application-name per document.

User agents may use the application name in UI in preference to the page’s title, since the title might include status messages and the like relevant to the status of the page at a particular moment in time instead of just being the name of the application.

To find the application name to use given an ordered list of languages (e.g., British English, American English, and English), user agents must run the following steps:

  1. Let languages be the list of languages.

  2. Let default language be the language of the Document's document element, if any, and if that language is not unknown.

  3. If there is a default language, and if it is not the same language as any of the languages in languages, append it to languages.

  4. Let winning language be the first language in languages for which there is a meta element in the Document that has its name attribute set to the value application-name and whose language is the language in question.

    If none of the languages have such a meta element, then abort these steps; there’s no given application name.

  5. Return the value of the content attribute of the first meta element in the Document in tree order that has its name attribute set to the value application-name and whose language is winning language.

This algorithm would be used by a browser when it needs a name for the page, for instance, to label a bookmark. The languages it would provide to the algorithm would be the user’s preferred languages.

author

The value must be a free-form string giving the name of one of the page’s authors.

description

The value must be a free-form string that describes the page. The value must be appropriate for use in a directory of pages, e.g., in a search engine or list of bookmarks.

generator

The value must be a free-form string that identifies one of the software packages used to generate the document. This value must not be used on pages whose markup is not generated by software, e.g., pages whose markup was written by a user in a text editor.

Here is what a tool called "Frontweaver" could include in its output, in the page’s head element, to identify itself as the tool used to generate the page:
<meta name=generator content="Frontweaver 8.2">
keywords

The value must be a set of comma-separated tokens, each of which is a keyword relevant to the page.

This page about typefaces on British motorways uses a meta element to specify some keywords that users might use to look for the page:
<!DOCTYPE HTML>
<html lang="en-GB">
  <head>
    <title>Typefaces on UK motorways</title>
    <meta name="keywords" content="british,type face,font,fonts,highway,highways">
  </head>
  <body>
  ...

Many search engines do not consider such keywords, because this feature has historically been used unreliably and even misleadingly as a way to spam search engine results in a way that is not helpful for users.

To obtain the list of keywords that the author has specified as applicable to the page, the user agent must run the following steps:

  1. Let keywords be an empty list.

  2. For each meta element with a name attribute and a content attribute and whose name attribute’s value is keywords, run the following substeps:

    1. Split the value of the element’s content attribute on commas.

    2. Add the resulting tokens, if any, to keywords.

  3. Remove any duplicates from keywords.

  4. Return keywords. This is the list of keywords that the author has specified as applicable to the page.

User agents should not use this information when there is insufficient confidence in the reliability of the value.

For instance, it would be reasonable for a content management system to use the keyword information of pages within the system to populate the index of a site-specific search engine, but a large-scale content aggregator that used this information would likely find that certain users would try to game its ranking mechanism through the use of inappropriate keywords.

referrer

The value must be a referrer policy, which defines the default referrer policy for the Document. [REFERRERPOLICY]

If any meta elements are inserted into the document or removed from the document, or existing meta elements have their name or content attributes changed, user agents must run the following algorithm:

  1. Let candidate elements be the list of all meta elements that meet the following criteria, in tree order:

    • The element is in a document tree
    • The element has a name attribute, whose value is referrer
    • The element has a content attribute, whose value is not the empty string
    • The element is a child of the head element of the document
  2. For each element in candidate elements:

    1. Let value be the value of element’s content attribute, converted to ASCII lowercase.

    2. If value is one of the values given in the first column of the following table, then set value to the value given in the second column:

      Legacy value Referrer policy
      never no-referrer
      default no-referrer-when-downgrade
      always unsafe-url
      origin-when-crossorigin origin-when-cross-origin
    3. If value is a referrer policy, then set element’s node document’s referrer policy to policy.

The fact that these steps are applied for each element enables deployment of fallback values for older user agents. [REFERRERPOLICY]

4.2.5.2. Other metadata names

Extensions to the predefined set of metadata names may be registered in the WHATWG Wiki MetaExtensions page. [WHATWGWIKI]

Anyone is free to edit the WHATWG Wiki MetaExtensions page at any time to add a type. These new names must be specified with the following information:

Keyword

The actual name being defined. The name should not be confusingly similar to any other defined name (e.g., differing only in case).

Brief description

A short non-normative description of what the metadata name’s meaning is, including the format the value is required to be in.

Specification

A link to a more detailed description of the metadata name’s semantics and requirements. It could be another page on the Wiki, or a link to an external page.

Synonyms

A list of other names that have exactly the same processing requirements. Authors should not use the names defined to be synonyms, they are only intended to allow user agents to support legacy content. Anyone may remove synonyms that are not used in practice; only names that need to be processed as synonyms for compatibility with legacy content are to be registered in this way.

Status

One of the following:

Proposed

The name has not received wide peer review and approval. Someone has proposed it and is, or soon will be, using it.

Ratified

The name has received wide peer review and approval. It has a specification that unambiguously defines how to handle pages that use the name, including when they use it in incorrect ways.

Discontinued

The metadata name has received wide peer review and it has been found wanting. Existing pages are using this metadata name, but new pages should avoid it. The "brief description" and "specification" entries will give details of what authors should use instead, if anything.

If a metadata name is found to be redundant with existing values, it should be removed and listed as a synonym for the existing value.

If a metadata name is registered in the "proposed" state for a period of a month or more without being used or specified, then it may be removed from the registry.

If a metadata name is added with the "proposed" status and found to be redundant with existing values, it should be removed and listed as a synonym for the existing value. If a metadata name is added with the "proposed" status and found to be harmful, then it should be changed to "discontinued" status.

Anyone can change the status at any time, but should only do so in accordance with the definitions above.

Conformance checkers may use the information given on the WHATWG Wiki MetaExtensions page to establish if a value is allowed or not: values defined in this specification or marked as "proposed" or "ratified" must be accepted, whereas values marked as "discontinued" or not listed in either this specification or on the aforementioned page must be reported as invalid. Conformance checkers may cache this information (e.g., for performance reasons or to avoid the use of unreliable network connectivity).

When an author uses a new metadata name not defined by either this specification or the Wiki page, conformance checkers should offer to add the value to the Wiki, with the details described above, with the "proposed" status.

Metadata names whose values are to be URLs must not be proposed or accepted. Links must be represented using the link element, not the meta element.

4.2.5.3. Pragma directives

When the http-equiv attribute is specified on a meta element, the element is a pragma directive.

The http-equiv attribute is an enumerated attribute. The following table lists the keywords defined for this attribute. The states given in the first cell of the rows with keywords give the states to which those keywords map. Some of the keywords are non-conforming, as noted in the last column.

State Keyword Notes
Content Language content-language Non-conforming
Encoding declaration content-type
Default style default-style
Refresh refresh
Cookie setter set-cookie Non-conforming

When a meta element is inserted into the document, if its http-equiv attribute is present and represents one of the above states, then the user agent must run the algorithm appropriate for that state, as described in the following list:

Content language state (http-equiv="content-language")

This feature is non-conforming. Authors are encouraged to use the lang attribute instead.

This pragma sets the pragma-set default language. Until such a pragma is successfully processed, there is no pragma-set default language.

  1. If the meta element has no content attribute, then abort these steps.

  2. If the element’s content attribute contains a U+002C COMMA character (,) then abort these steps.

  3. Let input be the value of the element’s content attribute.

  4. Let position point at the first character of input.

  5. Skip white space.

  6. Collect a sequence of characters that are not space characters.

  7. Let candidate be the string that resulted from the previous step.

  8. If candidate is the empty string, abort these steps.

  9. Set the pragma-set default language to candidate.

    If the value consists of multiple space-separated tokens, tokens after the first are ignored.

This pragma is not the same as the HTTP Content-Language header of the same name. HTTP Content-Language values with more than one language tag will be rejected as invalid by this pragma. [HTTP]

Encoding declaration state (http-equiv="content-type")

The encoding declaration state is just an alternative form of setting the charset attribute: it is a character encoding declaration. This state’s user agent requirements are all handled by the parsing section of the specification.

For meta elements with an http-equiv attribute in the encoding declaration state, the content attribute must have a value that is an ASCII case-insensitive match for a string that consists of: the literal string "text/html;", optionally followed by any number of space characters, followed by the literal string "charset=", followed by one of the labels of the character encoding of the character encoding declaration.

A document must not contain both a meta element with an http-equiv attribute in the encoding declaration state and a meta element with the charset attribute present.

The encoding declaration state may be used in HTML documents and in XML Documents. If the encoding declaration state is used in XML Documents, the name of the character encoding must be an ASCII case-insensitive match for the string "UTF-8" (and the document is therefore forced to use UTF-8 as its encoding).

The encoding declaration state has no effect in XML documents, and is only allowed in order to facilitate migration to and from XHTML.

Default style state (http-equiv="default-style")

This pragma sets the name of the default alternative style sheet set.

  1. If the meta element has no content attribute, or if that attribute’s value is the empty string, then abort these steps.

  2. Set the preferred style sheet set to the value of the element’s content attribute. [CSSOM]

Refresh state (http-equiv="refresh")

This pragma acts as timed redirect.

  1. If another meta element with an http-equiv attribute in the Refresh state has already been successfully processed (i.e., when it was inserted the user agent processed it and reached the step labeled end), then abort these steps.

  2. If the meta element has no content attribute, or if that attribute’s value is the empty string, then abort these steps.

  3. Let input be the value of the element’s content attribute.

  4. Let position point at the first character of input.

  5. Skip white space.

  6. Collect a sequence of characters that are ASCII digits, and parse the resulting string using the rules for parsing non-negative integers. If the sequence of characters collected is the empty string, then no number will have been parsed; abort these steps. Otherwise, let time be the parsed number.

  7. Collect a sequence of characters that are ASCII digits and U+002E FULL STOP characters (.). Ignore any collected characters.

  8. Let url be the meta element’s node document’s URL.

  9. If position is past the end of input, jump to the step labeled end.

  10. If the character in input pointed to by position is not a U+003B SEMICOLON character (;), a U+002C COMMA character (,), or a space character, then abort these steps.

  11. Skip white space.

  12. If the character in input pointed to by position is a U+003B SEMICOLON character (;), a U+002C COMMA character (,), then advance position to the next character.

  13. Skip white space.

  14. If position is past the end of input, jump to the step labeled end.

  15. Let url be equal to the substring of input from the character at position to the end of the string.

  16. If the character in input pointed to by position is a U+0055 LATIN CAPITAL LETTER U character (U) or a U+0075 LATIN SMALL LETTER U character (u), then advance position to the next character. Otherwise, jump to the step labeled skip quotes.

  17. If the character in input pointed to by position is a U+0052 LATIN CAPITAL LETTER R character (R) or a U+0072 LATIN SMALL LETTER R character (r), then advance position to the next character. Otherwise, jump to the step labeled Parse.

  18. If the character in input pointed to by position is a U+004C LATIN CAPITAL LETTER L character (L) or a U+006C LATIN SMALL LETTER L character (l), then advance position to the next character. Otherwise, jump to the step labeled Parse.

  19. Skip white space.

  20. If the character in input pointed to by position is a U+003D EQUALS SIGN (=), then advance position to the next character. Otherwise, jump to the step labeled Parse.

  21. Skip white space.

  22. Skip quotes: If the character in input pointed to by position is either a U+0027 APOSTROPHE character (') or U+0022 QUOTATION MARK character ("), then let quote be that character, and advance position to the next character. Otherwise, let quote be the empty string.

  23. Let url be equal to the substring of input from the character at position to the end of the string.

  24. If quote is not the empty string, and there is a character in url equal to quote, then truncate url at that character, so that it and all subsequent characters are removed.

  25. Parse: Parse url relative to the meta element’s node document. If that fails, abort these steps. Otherwise, let urlRecord be the resulting URL record.

  26. End: Perform one or more of the following steps:

    In addition, the user agent may, as with anything, inform the user of any and all aspects of its operation, including the state of any timers, the destinations of any timed redirects, and so forth.

For meta elements with an http-equiv attribute in the Refresh state, the content attribute must have a value consisting either of:

In the former case, the integer represents a number of seconds before the page is to be reloaded; in the latter case the integer represents a number of seconds before the page is to be replaced by the page at the given URL.

A news organization’s front page could include the following markup in the page’s head element, to ensure that the page automatically reloads from the server every five minutes:
<meta http-equiv="Refresh" content="300">
A sequence of pages could be used as an automated slide show by making each page refresh to the next page in the sequence, using markup such as the following:
<meta http-equiv="Refresh" content="20; URL=page4.html">
Cookie setter (http-equiv="set-cookie")

This pragma sets an HTTP cookie. [COOKIES]

It is non-conforming. Real HTTP headers should be used instead.

  1. If the meta element has no content attribute, or if that attribute’s value is the empty string, then abort these steps.

  2. Act as if receiving a set-cookie-string for the document’s URL via a "non-HTTP" API, consisting of the value of the element’s content attribute encoded as UTF-8. [COOKIES] [ENCODING]

Content security policy state (http-equiv="content-security-policy")

This pragma enforces a Content Security Policy on a Document. [CSP3]

  1. If the meta element is not a child of a head element, abort these steps.

  2. If the meta element has no content attribute, or if that attribute’s value is the empty string, then abort these steps.

  3. Let policy be the result of executing Content Security Policy’s parse a serialized Content Security Policy algorithm on the meta element’s content attribute’s value, with a source of "meta", and a disposition of "enforce".

  4. Remove all occurrences of the report-uri, frame-ancestors, and sandbox directives from policy.

  5. Enforce the policy policy.

For meta elements with an http-equiv attribute in the Content security policy state, the content attribute must have a value consisting of a valid Content Security Policy, but must not contain any report-uri, frame-ancestors, or sandbox directives. The Content Security Policy given in the content attribute will be enforced upon the current document. [CSP3]

A page might choose to mitigate the risk of cross-site scripting attacks by preventing the execution of inline JavaScript, as well as blocking all plugin content, using a policy such as the following:
<meta http-equiv="Content-Security-Policy" content="script-src 'self'; object-src 'none'">

There must not be more than one meta element with any particular state in the document at a time.

4.2.5.4. Other pragma directives

Extensions to the predefined set of pragma directives may, under certain conditions, be registered in the WHATWG Wiki PragmaExtensions page. [WHATWGWIKI]

Such extensions must use a name that is identical to an HTTP header registered in the Permanent Message Header Field Registry, and must have behavior identical to that described for the HTTP header. [IANAPERMHEADERS]

Pragma directives corresponding to headers describing metadata, or not requiring specific user agent processing, must not be registered; instead, use metadata names. Pragma directives corresponding to headers that affect the HTTP processing model (e.g., caching) must not be registered, as they would result in HTTP-level behavior being different for user agents that implement HTML than for user agents that do not.

Anyone is free to edit the WHATWG Wiki PragmaExtensions page at any time to add a pragma directive satisfying these conditions. Such registrations must specify the following information:

Keyword

The actual name being defined. The name must match a previously-registered HTTP name with the same requirements.

Brief description

A short non-normative description of the purpose of the pragma directive.

Specification

A link to the specification defining the corresponding HTTP header.

Conformance checkers must use the information given on the WHATWG Wiki PragmaExtensions page to establish if a value is allowed or not: values defined in this specification or listed on the aforementioned page must be accepted, whereas values not listed in either this specification or on the aforementioned page must be rejected as invalid. Conformance checkers may cache this information (e.g., for performance reasons or to avoid the use of unreliable network connectivity).

4.2.5.5. Specifying the document’s character encoding

A character encoding declaration is a mechanism by which the character encoding used to store or transmit a document is specified.

The following restrictions apply to character encoding declarations:

In addition, due to a number of restrictions on meta elements, there can only be one meta-based character encoding declaration per document.

If an HTML document does not start with a BOM, and its encoding is not explicitly given by Content-Type metadata, and the document is not an iframe srcdoc document, then the character encoding used must be an ASCII-compatible encoding, and the encoding must be specified using a meta element with a charset attribute or a meta element with an http-equiv attribute in the encoding declaration state.

A character encoding declaration is required (either in the Content-Type metadata or explicitly in the file) even if the encoding is US-ASCII, because a character encoding is needed to process non-ASCII characters entered by the user in forms, in URLs generated by scripts, and so forth.

If the document is an iframe srcdoc document, the document must not have a character encoding declaration. (In this case, the source is already decoded, since it is part of the document that contained the iframe.)

If an HTML document contains a meta element with a charset attribute or a meta element with an http-equiv attribute in the encoding declaration state, then the character encoding used must be an ASCII-compatible encoding.

Authors should use UTF-8. Conformance checkers may advise authors against using legacy encodings. [ENCODING]

Authoring tools should default to using UTF-8 for newly-created documents. [ENCODING]

Authors must not use encodings that are not defined in the WHATWG Encoding specification. Additionally, authors should not use ISO-2022-JP. [ENCODING]

Some encodings that are not defined in the WHATWG Encoding specification use bytes in the range 0x20 to 0x7E, inclusive, to encode characters other than the corresponding characters in the range U+0020 to U+007E, inclusive, and represent a potential security vulnerability: A user agent might end up interpreting supposedly benign plain text content as HTML tags and JavaScript.

Using non-UTF-8 encodings can have unexpected results on form submission and URL encodings, which use the document’s character encoding by default.

In XHTML, the XML declaration should be used for inline character encoding information, if necessary.

In HTML, to declare that the character encoding is UTF-8, the author could include the following markup near the top of the document (in the head element):
<meta charset="utf-8">

In XML, the XML declaration would be used instead, at the very top of the markup:

<?xml version="1.0" encoding="utf-8"?>

4.2.6. The style element

Categories:
Metadata content.
Contexts in which this element can be used:
Where metadata content is expected.
In a noscript element that is a child of a head element.
In the body, where flow content is expected.
Content model:
Depends on the value of the type attribute, but must match requirements described in prose below.
Tag omission in text/html:
Neither tag is omissible.
Content attributes:
Global attributes
media — Applicable media
type — Type of embedded resource
Also, the title attribute has special semantics on this element: Alternative style sheet set name.
Allowed ARIA role attribute values:
None
Allowed ARIA state and property attributes:
None
DOM interface:
interface HTMLStyleElement : HTMLElement {
  attribute DOMString media;
  attribute DOMString type;
};
HTMLStyleElement implements LinkStyle;

The style element allows authors to embed style information in their documents. The style element is one of several inputs to the styling processing model. The element does not represent content for the user.

The type attribute gives the styling language. If the attribute is present, its value must be a valid mime type that designates a styling language. The charset parameter must not be specified. The default value for the type attribute, which is used if the attribute is absent, is "text/css". [RFC2318]

When examining types to determine if they support the language, user agents must not ignore unknown MIME parameters — types with unknown parameters must be assumed to be unsupported. The charset parameter must be treated as an unknown parameter for the purpose of comparing MIME types here.

The media attribute says which media the styles apply to. The value must be a valid media query list. The user agent must apply the styles when the media attribute’s value matches the environment and the other relevant conditions apply, and must not apply them otherwise.

The styles might be further limited in scope, e.g., in CSS with the use of @media blocks. This specification does not override such further restrictions or requirements.

The default, if the media attribute is omitted, is "all", meaning that by default styles apply to all media.

A style element should preferably be used in the head of the document. The use of style in the body of the document may cause restyling, trigger layout and/or cause repainting, and hence, should be used with care.

The title attribute on style elements defines alternative style sheet sets. If the style element has no title attribute, then it has no title; the title attribute of ancestors does not apply to the style element. [CSSOM]

The title attribute on style elements, like the title attribute on link elements, differs from the global title attribute in that a style block without a title does not inherit the title of the parent element: it merely has no title.

The textContent of a style element must match the style production in the following ABNF, the character set for which is Unicode. [ABNF]

style         = no-c-start *( c-start no-c-end c-end no-c-start )
no-c-start    = < any string that doesn’t contain a substring that matches c-start >
c-start       = "<!--"
no-c-end      = < any string that doesn’t contain a substring that matches c-end >
c-end         = "-->"

The user agent must run the update a style block algorithm that applies for the style sheet language specified by the style element’s type attribute, passing it the element’s style data, whenever one of the following conditions occur:

For styling languages that consist of pure text (as opposed to XML), a style element’s style data is the child text content of the style element (not any other nodes such as comments or elements), in tree order. For XML-based styling languages, the style data consists of all the child nodes of the style element.

The update a style block algorithm for CSS (text/css) is as follows:

  1. Let element be the style element.

  2. If element has an associated CSS style sheet, remove the CSS style sheet in question.

  3. If element is not in a Document, then abort these steps.

  4. If the Should element’s inline behavior be blocked by Content Security Policy? algorithm returns "Blocked" when executed upon the style element, "style", and the style element’s style data, then abort these steps. [CSP3]

  5. create a CSS style sheet with the following properties:

    type

    text/css

    owner node

    element

    media

    The media attribute of element.

    This is a reference to the (possibly absent at this time) attribute, rather than a copy of the attribute’s current value. The CSSOM specification defines what happens when the attribute is dynamically set, changed, or removed.

    title

    The title attribute of element.

    Again, this is a reference to the attribute.

    alternate flag

    Unset.

    origin-clean flag

    Set.

    parent CSS style sheet
    owner CSS rule

    null

    disabled flag

    Left at its default value.

    CSS rules

    Left uninitialized.

This specification does not define any other styling language’s update a style block algorithm.

Once the attempts to obtain the style sheet’s critical subresources, if any, are complete, or, if the style sheet has no critical subresources, once the style sheet has been parsed and processed, the user agent must, if the loads were successful or there were none, queue a task to fire a simple event named load at the style element, or, if one of the style sheet’s critical subresources failed to completely load for any reason (e.g., DNS error, HTTP 404 response, a connection being prematurely closed, unsupported Content-Type), queue a task to fire a simple event named error at the style element. Non-network errors in processing the style sheet or its subresources (e.g., CSS parse errors, PNG decoding errors) are not failures for the purposes of this paragraph.

The task source for these tasks is the DOM manipulation task source.

The element must delay the load event of the element’s node document until all the attempts to obtain the style sheet’s critical subresources, if any, are complete.

This specification does not specify a style system, but CSS is expected to be supported by most Web browsers. [CSS-2015]

The media, and type IDL attributes must reflect the respective content attributes of the same name.

The LinkStyle interface is also implemented by this element. [CSSOM]

The following document has its stress emphasis styled as bright red text rather than italics text, while leaving titles of works and Latin words in their default italics. It shows how using appropriate elements enables easier restyling of documents.
<!DOCTYPE html><html>
  <head>
    <title>My favorite book</title>
    <style>
      body { color: black; background: white; }
      em { font-style: normal; color: red; }
    </style>
  </head>
  <body>
    <p>My <em>favorite</em> book of all time has <em>got</em> to be
    <cite>A Cat’s Life</cite>. It is a book by P. Rahmel that talks
    about the <i lang="la">Felis Catus</i> in modern human society.</p>
  </body>
</html>

4.2.7. Interactions of styling and scripting

Style sheets, whether added by a link element, a style element, an <?xml-stylesheet?> PI, an HTTP Link header, or some other mechanism, have a style sheet ready flag, which is initially unset.

When a style sheet is ready to be applied, its style sheet ready flag must be set. If the style sheet referenced no other resources (e.g., it was an internal style sheet given by a style element with no @import rules), then the style rules must be immediately made available to script; otherwise, the style rules must only be made available to script once the event loop reaches its update the rendering step.

A style sheet in the context of the Document of an HTML parser or XML parser is said to be a style sheet that is blocking scripts if the element was created by that Document's parser, and the element is either a style element or a link element that was an external resource link when the element was created by the parser, and the element’s style sheet was enabled when the element was created by the parser, and the element’s style sheet ready flag is not yet set, and, the last time the event loop reached step 1, the element was in that Document, and the user agent hasn’t given up on that particular style sheet yet. A user agent may give up on a style sheet at any time.

Giving up on a style sheet before the style sheet loads, if the style sheet eventually does still load, means that the script might end up operating with incorrect information. For example, if a style sheet sets the color of an element to green, but a script that inspects the resulting style is executed before the sheet is loaded, the script will find that the element is black (or whatever the default color is), and might thus make poor choices (e.g., deciding to use black as the color elsewhere on the page, instead of green). Implementors have to balance the likelihood of a script using incorrect information with the performance impact of doing nothing while waiting for a slow network request to finish.

A Document has a style sheet that is blocking scripts if there is either a style sheet that is blocking scripts in the context of that Document, or if that Document is in a browsing context that has a parent browsing context, and the active document of that parent browsing context itself has a style sheet that is blocking scripts.

A Document has no style sheet that is blocking scripts if it does not have a style sheet that is blocking scripts as defined in the previous paragraph.

4 The elements of HTMLTable of contents4.3 Sections