The Frontmatter

In the following list, Frontmatter lines are highlighted with emoji:

• ❗ = Required
• 🌐 = Required for translation interoperability and should be edited by translators.
• 🚸 = Do not use unless absolutely needed. – Frontmatter lines are often used to provide non-standard and limited use-case functionality. If often used to solve a specific use case, it is better to develop that feature properly.

Title

title ❗🌐

A title that describes the page. Will be used as an h1 and in the HTML title.

Note: When using colons (:) in the values of the Frontmatter, using straight (") or single (') quotes is required.

title_html 🌐🚸

If you need to use HTML in the title (for example to highlight a word, use code markup or force a line break), you can use this line to provide that HTML variant. The title will still be used in the HTML title, for example, or when referring to the page using WAI Markdown links.

nav_title ❗🌐

A short title that we’ll use as the navigation text (in the left navigation) in the future. It should be short and succinct.

title_image 🌐

To right-float an image on the title, specify it in the title_image line. If the image contains text, it needs to be adjusted to the language of the document.

title_icon 🌐

An icon that is displayed left of the <h1>.

lang ❗🌐

Specify the language of the current document. Use the two-letter code, and if needed add specifiers by appending them using dashes (-). An up to date list of language codes can be found here on iana.org. Search for the language and then look for subtag.

Note: pt-BR above means “Portuguese as spoken in Brazil”. We usually only use region identifier when the language is significantly differently interpreted in different regions or when there is a reasonable expectation to get diverging translations.

permalink ❗🌐

This determines where a page will be put when the site is generated.

For English pages it looks like this: /path/to/page/. Note that it does not use /WAI/ or https://www.w3.org/.

For translations, add the language code to the end of the permalink, like /path/to/page/es for Spanish or /path/to/page/de for German

Note: By convention, translations do not get a closing forward slash /.

ref ❗🌐

The unique identifier (“reference”) of a page. It uses the permalink of the English version of the page and is used (among other things) to identify the set of translations of a page.

last_updated 🌐

A ISO date that specifies when the document was last edited in the format of YYYY-MM-DD (e.g. 2019-03-07 or 2020-11-24).

Note: We do not version our pages and we also do not keep old versions. Occasionally we use change logs to highlight changes between versions but there is no way translators can tell by looking at the date(s) if there were major or minor changes.

translators 🌐

Every translator is specified by their name in a separate line, like:

In addition, links can be added (note: there are strict rules of which pages to link to):

contributors 🌐

Every (translation!) contributor is specified by their name in a separate line, like:

In addition, links can be added (note: there are strict rules of which pages to link to):

github ❗🌐

The github key defines the repository, branch and path of the document to provide the fork and edit this document on GitHub links.

For translations, the language abbreviation is put between the filename and the extension. Examples:

• index.md ➡️ index.de.md
• this-is-a-longer-name.md ➡️ this-is-a-longer-name.el.md

footer ❗🌐

The footer has information about the document. The content of the footer needs to be translated.

changelog

The changelog attribute uses a reference to another document and replaces the token CHANGELOG in the footer text with a link to the changelog.

acknowledgements

The acknowledgements attribute uses a reference to another document and replaces the token ACKNOWLEDGEMENTS in the footer text with a link to the acknowledgements.

license

Define a license for the content. If no license is set, the W3C Document License is assumed. Specify creative-commons to output a paragraph in the footer area that links to the Creative Commons license and sets the metadata of the page appropriately.

• Creative Commons (creative-commons) — include for resources we specifically want people to adapt for their environment, such as sample presentations, curricula, business case. For now, do not include on other things.

navigation

Navigation specifies next and previous pages (by their ref reference), so that previous/next arrows can be shown:

class

Sometimes it is useful to specify a class on the body element. (Note that the page automatically creates a class with the name of the current page on the body element.)

• tight-page: Uses less space above h2 headings, mainly used on for overview-ish pages.

feedbackmail

In the “Help improve this page” box, the default e-mail address (in text and buttons) is wai-eo-editors@w3.org
To change that, use feedbackmail.

footnotestitle

The title used as a heading of the Footnotes list box. Falls back to ”Footnotes”.

SEO & Social Media Metadata

Most of the SEO/SM metadata is provided by the Jekyll SEO Tag plugin. We provide sensible metadata by default, however two lines should be added to the Frontmatter to customize Social Media preview:

description 🌐

Provide a short description of what the page is all about.

image 🌐

Provide a short social media sharing image. This image might also be re-used when linking to a page from other sections of the website, for example as a home page teaser¹.