View source for WAI/Website/Anatomy of a Document

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. [https://github.com/w3c/wai-resource-template/blob/master/index.md Page source] and [https://wai-resource-template.netlify.com/ rendered output].

== The Frontmatter ==

The frontmatter starts and ends with a line of three dashes: <code>---</code> and typically looks like this ([https://gist.github.com/yatil/828849687b9bc4cd1a0429b3f5de75d9 version with code highlighting]):

<pre>---
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>
---</pre>

The frontmatter uses a standard [https://yaml.org yaml syntax].

=== Frontmatter Values ===

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

==== <code>title</code> ❗🌐 ====

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

==== <code>nav_title</code> 🌐 ====

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

==== <code>title_html:</code> ?🌐 ====

@@

==== <code>ref</code> ❗🌐 ====

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.

==== <code>permalink</code> ❗🌐 ====

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

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

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

==== <code>lang</code> ❗🌐 ====

Specify the language of the current document

==== <code>last_updated</code> 🌐 ====

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

==== <code>translators</code> 🌐 ====

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

<pre>translators:
- name: &quot;Ms Smith&quot;
- name: &quot;Mr Smith&quot;</pre>
In addition, links can be added (note: there are strict [https://www.w3.org/WAI/about/translating/#links rules of which pages to link to]):

<pre>translators:
- name: &quot;Ms Smith&quot;
  link: &quot;https://smithspersonalhomepage.example.com&quot;
- name: &quot;Mr Smith&quot;</pre>

==== <code>contributors</code> 🌐 ====

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

<pre>contributors:
- name: &quot;Ms Smith&quot;
- name: &quot;Mr Smith&quot;</pre>
In addition, links can be added (note: there are strict [https://www.w3.org/WAI/about/translating/#links rules of which pages to link to]):

<pre>contributors:
- name: &quot;Ms Smith&quot;
  link: &quot;https://smithspersonalhomepage.example.com&quot;
- name: &quot;Mr Smith&quot;</pre>

==== <code>github</code> ❗🌐 ====

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

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

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

* <code>branch</code> ➡️ <code>master</code>
* <code>path</code> ➡️ <code>index.md</code>

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

* <code>index.md</code> ➡️ <code>index.de.md</code> 
* <code>this-is-a-longer-name.md</code> ➡️ <code>this-is-a-longer-name.el.md</code>

==== <code>footer</code> ❗🌐 ====

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

<pre>footer: &gt;
  &lt;p&gt;Footer Content as HTML.&lt;/p&gt;</pre>

==== <code>navigation</code>  ====

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

<pre>navigation:
  previous: /path/to/previous/file/
  next: /path/to/next/file/</pre>

== 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:

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

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

<pre>{::options parse_block_html="true" /}

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

=== 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 [https://daringfireball.net/projects/markdown/basics Markdown Basics], the [https://daringfireball.net/projects/markdown/syntax Full Syntax] and [https://help.github.com/en/articles/creating-and-highlighting-code-blocks 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:

<pre>{::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" %}
{:/}</pre>

====== Optional Attributes: ======

You can combine all the following attributes.

* For different '''variants''' (see below): add the class attribute to the opening tag, like: <pre>{% include box.html type="start" class="simple" title="Box Heading" %}</pre>

* To use a '''heading level''', the following syntax will generate a heading level 3: <pre>{% include box.html type="start" h="3" title="Box Heading" %}</pre>

* Add the id attribute to '''set an ID''' (you have to make sure that this ID is unique on the page): <pre>{% include box.html type="start" id="example" title="Box Heading" %}</pre>

* Add an '''icon''' to the heading by specifying an icon name, for exampe, [https://w3c.github.io/wai-website-components/components/detail/icons--code.html code]:  <pre>{% include box.html type="start" icon="code" title="Box Heading" %}</pre>

====== Variants ======

* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--default.html Default] (no class)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--simple.html Simple] (<code>class="simple"</code>)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--large.html Large] (<code>class="large"</code>)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--large-icon.html Large w/ Icon] (<code>class="large"</code>)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--large-icon-link-list.html Large w/ Icon and Link List] (<code>class="large linklist"</code>)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--large-icon-unordered-with-link.html Large w/ Icon and Link List with Descriptions] (<code>class="large links"</code>)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--float-right.html Float Right] (<code>class="right"</code>)
* [https://w3c.github.io/wai-website-components/components/detail/box-wrapper--float-right-small.html Float Right, Smaller Text] (<code>class="right aside"</code>)

==== Specialized Markdown Syntax ====

===== Link Treatment =====

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

====== '''Standard Markdown Links''': <code>[Link Text](/path/to/page/)</code> ======

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 [https://www.w3.org/WAI/fundamentals/accessibility-principles/ accessibility principles], you can use the following link:

<pre class="markdown">It is important to look at [basic principles](/fundamentals/accessibility-principles/) that are fundamental to make a website accessible.</pre>
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''': <code><nowiki>[[Title of the Page]](/path/to/page/)</nowiki></code> ======

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:

<pre class="markdown">More information is available in: <nowiki>[[Accessibility Principles]](/fundamentals/accessibility-principles/)</nowiki></pre>
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.