WAI Tutorials Flavored Markdown

Markdown in General

Markdown is a general purpose markup language for web content. It uses simple ASCII characters to denote individual HTML elements. Example:

# Heading

is transferred to

<h1>Heading</h1>

In general these tutorials use GitHub flavored markdown as described here:

• http://daringfireball.net/projects/markdown/
• https://guides.github.com/features/mastering-markdown/

Tutorial specific uses

As the tutorials use the static site generator Middleman, we have been able to extend Markdown’s native capabilities.

The frontmatter

Each content file has a front matter that looks like this:

---
title: Labeling Regions
nav_title: Labels
order: 3
wcag_success_criteria:
  - 2.4.1
  - 2.4.6
wcag_techniques:
  - H69
  - ARIA11
technologies: HTML5, WAI-ARIA
editors:
- Eric Eggert: "https://www.w3.org/People/yatil/"
- Shadi Abou-Zahra: "https://www.w3.org/People/shadi/"
contributors:
- The Education and Outreach Working Group (<a href="https://www.w3.org/WAI/EO/">EOWG</a>)
support: Developed with support from the <a href="https://www.w3.org/WAI/ACT/">WAI-ACT project</a>, co-funded by the <strong>European Commission <abbr title="Information Society Technologies">IST</abbr> Programme</strong>.
---

The title is the <h1> on the page and also used in the page title. The nav_title is used in the left hand navigation. If it’s not present, the title is used.

order signals the order of the page in the tutorial. 1 is the concepts page.

wcag_success_criteria and wcag_techniques denote the used SCs and techniques on the page, so they don’t need to be copied and pasted into the document.

technologies are used as tags.

Content blocks

Content blocks are used to show examples or code snippets. They can also be used to show sidebar content.

Code syntax

{::nomarkdown}
<%= code_start %>
{:/}

~~~html
<nav aria-labelledby="regionheading">
  <h3 id="regionheading">On this Page</h3>
    …
</nav>
~~~

{::nomarkdown}
<%= code_end %>
{:/}

This code switches markdown off and renders a snippet for the start of the code block. Then markdown is switched on again, and normal markdown markup continues. Afterward, code_end closes the elements that were previously opened.

Examples

{::nomarkdown}
<%= sample_start %>
{:/}

Example code

{::nomarkdown}
<%= sample_end %>
{:/}

Same as with code syntax blocks.

References and Links to demos.

References

We use brown-ish bordered boxes to link to more information like standards. Those items need three tokens to put into the text so that the layout can work out:

{::nomarkdown}
<%= ref :start %>
{:/}

… is put before the content where the reference is supposed to be next to. Then the following code is used:

{::nomarkdown}
<%= ref :middle %>
{:/}

It is followed by the actual reference. Then the divs are closed with:

{::nomarkdown}
<%= ref :end %>
{:/}

Demos

The same as references above, but with the keyword demo instead of ref.