Documentation on file and structure requirements from w3c/aria-practices #399
Description
Follow on from #390. The below is a documentation draft on presenting the hidden expectations and requirements on content that needs to be transformed from aria-practices to be presented on the WAI website:
Background
The w3c/aria-practices contains the source content for the WAI-ARIA Authoring Practices Guidelines Website. The translations which allow the website to properly build exist in w3c/wai-aria-practices.
As such, contributions from w3c/aria-practices are expected to follow a certain structure to be properly translated by w3c/wai-aria-practices to avoid any "data-to-template" rendering issues.
Basic structure expectations
- Content to be rendered must exist in the
/contentfolder. - Practices (served from
/content/practices):- The index file is served from
/content/practices/practices.html - Each sub-folder in
/content/practicesshould have aSUBFOLDER_NAME-practice.htmlso the expected practice page is rendered. Eg./content/practices/landmark-regions/landmark-regions-practice.html
- The index file is served from
- Patterns (served from
/content/patterns):- The index file is served from
/content/patterns/patterns.html - Each sub-folder in
/content/patternsshould have aSUBFOLDER_NAME-pattern.htmlso the expected pattern page is rendered. Eg./content/patterns/alert/alert-pattern.html - Example content is located under
/content/patterns/SUBFOLDER_NAME/examples/*
- The index file is served from
- Image assets must be one of the following formats:
.svg,.pngor.jpg.
Technical expectations of file types
For the purposes of completing the expected file transformations, there are several defined file types, which each have their own expectations:
aboutIndex
- Sourced from
/content/about/about.html. - Required elements:
<head><body><h1><h2><main>containing:- a
<ul>element
- a
aboutPage
- Sourced from all
/content/about/**/*.htmlfiles. - Required elements:
<head><body><h1><h2>
- Special cases:
- The file
/content/about/coverage-and-quality-report.htmlmust include:- At least 1
<p>element which contains the textPage last updated:
- At least 1
- The file
example
- Sourced from all
/content/patterns/**/examples/*.htmlfiles. - Required elements:
<head><body><main>, which may include optionaldata-content-phase="experimental"attribute- An element with
aria-label="Related Links"containing:- a
<ul>which has at least 1<li>which has anaelement containing the text "Related Issues"
- a
- Special cases:
- There exists files at
content/shared/templates/example-usage-warning.htmlandcontent/shared/templates/experimental-example-usage-warning.html, which has the following:<body>
- There exists files at
exampleIndex
- Sourced from
/content/index/index.html. - Required elements:
<head><body><h1>
homepage
- Sourced from
/content/apg-home.html. - Required elements:
<head><body>
- Expected id-defined sections:
- #top-card
<h1><p><a><img>
- #resources
<h2><p>- 1 or more
<li>elements, each containing:<h3><p><a><img>
- #collaboration
<h2><p>- More than 1
<li>elements, each containing:<h3><p><a>(not expected for the last<li>)<img>
- #top-card
htmlAsset
Serves a static .html file directly without any WAI related wrappers.
- Sourced from
/scripts/pre-build/library/.tracked-html-assets.json.
imageAsset
- Sourced from the following file types:
.svg.png.jpg
otherAsset
Every other non-.html file (eg. .js, .css)
- Special handling done here for
/content/shared/js/app.js. - Special handling done here for
/content/shared/js/skipto.js.
pattern
- Sourced from all
/content/patterns/**/*-pattern.htmlfiles. - Required elements:
<head><body><h1>- 1 or more
<section>elements:- If the
<section>element has an<h2>element with the text containing either "Example" or "Examples", it is designated as the "Examples Section" by attaching anexamples-sectionclass.
- If the
patternIndex
- Sourced from
/content/patterns/patterns.html. - Required elements:
<head><body><h1>
- Special cases:
- There exists a file at
content/shared/templates/read-this-first.html, which has the following:<body>
- There exists a file at
practice
- Sourced from all
/content/practices/**/*-practice.htmlfiles. - Required elements:
<head><body><h1>
practiceIndex
- Sourced from
/content/practices/practices.html. - Required elements:
<head><body><h1>