This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.

[Draft] Minimal Header and 'standalone_resource' Layout

Note: We are updating this documentation. Your patience is appreciated.
Please send any questions to Steve and Shawn.
Feel free to submit a Pull Request for improvements to this documentation. Thanks!

Background and what’s what

The main WAI website header and navigation takes up a fair bit of screen real estate and adds some visual complexity to pages. We don’t want that for some WAI resources; for example, the WCAG-EM Report Tool and Supplemental Guidance to WCAG 2.

A few things evolved in ways that make the current naming not aligned with reality. We decided not to further change the names of existing components and layouts. There are two related things:

  1. minimal header component
  2. standalone_resource layout — which is actually for things that are integrated into the WAI website theme

Resources that are integrated

Resources that are fully integrated into the WAI website and use the WAI theme, use the ‘stand-alone resources’ layout. This is currently used for document sets, such as Supplemental Guidance to WCAG, and interactive Lists, such as (coming in 2022).

With the layout, you can:

These are all configured declaratively using page variables in the usual Jekyll way. They can be specified per page in the frontmatter, or across pages in the _config.yml file. (See Jekyll - Front Matter Defaults). Specifying them in the config file is usually best.

Specify the ‘stand-alone resources’ layout

layout: standalone_resource

Hint: You can use nested layouts to save repetition.

Header, name of set of resources and tagline

Required: The name of the set of documents.

Optional: A subtitle or tagline.

standalone_resource_header:
  title: Supplemental Guidance to WCAG 2
  subtitle: Additional ways to improve accessibility, not required to meet WCAG
standalone_resource_header:
  link:
    ref: /WCAG2/supplemental/about/
    title: About Supplemental Guidance and WCAG

The icon is optional.

standalone_resource_pager:
  icon: /content-images/wai-wcag-supplemental/brain.svg
  name: All Cognitive
  ref: /WCAG2/supplemental/#cognitiveaccessibilityguidance```

Pager in navigation, optional

The pager provides ‘up’, ‘next’ and ‘previous’ links for navigation within the set of documents. It is data driven, using a set of Jekyll arrays to provide the names and URLs.

To use it, specify an include file that provides the arrays.

standalone_resource_pager:
  include: dg-pager.liquid

For example: Here’s the code from at the end of the Supplemental Guidance pager file dg-pager.liquid:

{% comment %}
Set up tuples for pager
{% endcomment %}
{% if is_pattern %}
    {% assign item_type = "Pattern" %}
    {% assign context_type = "Objective" %}
{% else %}
    {% assign item_type = "Objective" %}
{% endif %}
{% if prev_item %}
    {% assign prev = "Previous " | append: item_type | append: "??" | append: prev_item.url | append: "??" | append: prev_item.title | split: "??" %}
{% endif %}
{% if next_item %}
    {% assign next = "Next " | append: item_type | append: "??" | append: next_item.url | append: "??" | append: next_item.title | split: "??" %}
{% endif %}
{% if context_item %}
    {% assign context = context_type | append: "??" | append: context_item.url | append: "??" | append: context_item.title | split: "??" %}
{% endif %}
{% endif %}

@@ TODO: explain this

Type of document (guidance) in h1, optional

Most document sets have different types of documents, for example the cognitive guidance has ‘Objectives’ and ‘Design Patterns’. The type of document is included at the beginning of the h1. It can also be used for other logic purposes in the resource pages.

Provide the type_of_guidance and if it is proposed.

type_of_guidance: Technique

In addition, if defined, “proposed” is use as a prefix.

proposed: true

Generated Page Contents, optional

A right-hand sidebar can be enabled that provides navigation to headings. By default, it includes h2. You can set it to include other heading levels. In addition to the the sidebar menu, it adds the fragment id’s for the URLs to the headings.

sidebar: true

Tools that are not integrated

Some tools — currently WCAG-EM Report Tool and ATAG Report Tool — do not use the WAI website theme. Instead they are implemented in other technologies and linked into the WAI website via W3C redirects. They use the Tool version of the Minimal Header and use the theme styles, including those for the Minimal Header for visual consistency with the WAI website.

Tool navigation, depreciated

For tools that have all pages in the navigation area, a set of tab-like links are created thus:

standalone_resource_nav_links:
  - name: Tab1
    ref: /path/to/page1
  - name: Tab2
    ref: /path/to/page2

This is not compatible with the navigation described above.

Examples

Back to Top

This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.