WAI/Website/Anatomy of a Document

From W3C Wiki
< WAI‎ | Website

A document consists of a frontmatter, a configuration section, and the actual content of the page. A simple but straightforward example of a markdown page can be found at the resource template. Page source and rendered output.

The Frontmatter

The frontmatter starts and ends with a line of three dashes: --- and typically looks like this (version with code highlighting): 

---
title: "This is the Title of the Page"
nav_title: "Short title"
permalink: /link/to/page/
ref: /link/to/page/   # Do not change this
lang: en
last_updated: 2019-03-07
translators: 
- name: "Your Name"
- name: "Other Name"
contributors:
- name: "Other Name"
layout: default
github:
   repository: w3c/wai-repository
   path: 'index.md'
footer: >
   <p>Footer Content as HTML.</p>
---

The frontmatter uses a standard yaml syntax.

Frontmatter Values

  • ❗ = Required
  • 🌐 = Required for translations/translated documents and should be edited by translators.

title ❗🌐

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

nav_title 🌐

A short title that we plan to use in the navigation.

title_html: ?🌐

@@

ref ❗🌐

The unique identifier of a page. It uses the permalink of the English version of the page and is used to identify the set of translations of a page.

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

lang ❗🌐

Specify the language of the current document

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).

translators 🌐

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

translators:
- name: "Ms Smith"
- name: "Mr Smith"

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

translators:
- name: "Ms Smith"
  link: "https://smithspersonalhomepage.example.com"
- name: "Mr Smith"

contributors 🌐

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

contributors:
- name: "Ms Smith"
- name: "Mr Smith"

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

contributors:
- name: "Ms Smith"
  link: "https://smithspersonalhomepage.example.com"
- name: "Mr Smith"

github ❗🌐

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

github:
  repository: w3c/wai-repository
  branch: master
  path: 'index.md'

The defaults are, so don’t specify them if they have the default value:

  • branch ➡️ master
  • path ➡️ index.md

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. 

footer: >
  <p>Footer Content as HTML.</p>

navigation

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

navigation:
  previous: /path/to/previous/file/
  next: /path/to/next/file/

Formatting Content

In general, we recommend writing content for the site in Markdown as it is easier to review on GitHub, updates the table of contents automatically and also receives special treatment for links that allow for ease of translations. HTML and Markdown can be mixed, when you do that, do not indent the first HTML tag.

HTML

Usually, if HTML is used, the section is not parsed with Markdown.

The following code will not result in the output of a link: 

<p>This is a HTML with an [embedded Markdown link](http://example.com).</p>

If you want to use inline-markdown in HTML elements, you can add the {::options parse_block_html="true" /} directive. This will give you the option to use specific WAI extensions to Markdown in The following will work: 

{::options parse_block_html="true" /}

<p>This is a HTML with an [embedded Markdown link](http://example.com).</p>

Markdown

Markdown is a way to write HTML content in a simplified language that is easy to read and compare and provide less distraction from the process of writing itself.

You can learn more about the Markdown Basics, the Full Syntax and Syntax highlighting from “Github-flavored Markdown”.

This is the particular parser we are using, it has interesting tips and tricks in it: https://kramdown.gettalong.org/quickref.html

WAI specific extensions

(to be added)

Templates

The following template includes are available for editors to use. Note that those includes are a little bit more complicated than the Markdown extensions below. (We might decide to convert the following templates into a simpler syntax eventually.)

Boxes

Boxes are a standard way to break up content into sections.

Syntax

The box consists of two “Tags”: The start of the box, and the end of the box: 

{::nomarkdown}
{% include box.html type="start" title="Box Heading" %}
{:/}

Lorem ipsum dolor sit amet, consectetur adipisicing elit. Ratione placeat ab laboriosam. Assumenda aut, praesentium commodi nesciunt natus ipsum fugiat voluptates nisi ipsam voluptas recusandae, a. Sunt eos veritatis numquam!

{::nomarkdown}
{% include box.html type="end" %}
{:/}
Optional Attributes:

You can combine all the following attributes.

  • For different variants (see below): add the class attribute to the opening tag, like: 
    {% include box.html type="start" class="simple" title="Box Heading" %}
  • To use a heading level, the following syntax will generate a heading level 3: 
    {% include box.html type="start" h="3" title="Box Heading" %}
  • Add the id attribute to set an ID (you have to make sure that this ID is unique on the page): 
    {% include box.html type="start" id="example" title="Box Heading" %}
  • Add an icon to the heading by specifying an icon name, for exampe, code: 
    {% include box.html type="start" icon="code" title="Box Heading" %}
Variants

Specialized Markdown Syntax

Link Treatment

This behavior differs significantly from the standard way Markdown treats links:

Standard Markdown Links: [Link Text](/path/to/page/)

Links that link to a page on the WAI site can use the permalink to that page as an identifier. This permalink is relative to the main WAI directory. For example, if you wanted to link to the accessibility principles, you can use the following link: 

It is important to look at [basic principles](/fundamentals/accessibility-principles/) that are fundamental to make a website accessible.

If you want to use links that are relative to w3.org, use the complete absolute URL: https://www.w3.org/blog/

Title Markdown Links: [[Title of the Page]](/path/to/page/)

If you want to use the title of the page you are linking to, use the double square brackets. A special plugin will identify the page based on the permalink and insert the title of the page as the link text. Example: 

More information is available in: [[Accessibility Principles]](/fundamentals/accessibility-principles/)

This is useful for several use cases: When the title of a resource changes, all links get updated with the title of the resource. Also, translators can translate the page title in their translations but once the page is actually translated, all links to the translation are updated to use the “one true” title of the document.

Retrieved from "https://www.w3.org/wiki/index.php?title=WAI/Website/Anatomy_of_a_Document&oldid=109648"