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
/content folder.
- Practices (served from
/content/practices):
- The index file is served from
/content/practices/practices.html
- Each sub-folder in
/content/practices should have a SUBFOLDER_NAME-practice.html so the expected practice page is rendered. Eg. /content/practices/landmark-regions/landmark-regions-practice.html
- Patterns (served from
/content/patterns):
- The index file is served from
/content/patterns/patterns.html
- Each sub-folder in
/content/patterns should have a SUBFOLDER_NAME-pattern.html so the expected pattern page is rendered. Eg. /content/patterns/alert/alert-pattern.html
- Example content is located under
/content/patterns/SUBFOLDER_NAME/examples/*
- Image assets must be one of the following formats:
.svg, .png or .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:
aboutPage
- Sourced from all
/content/about/**/*.html files.
- Required elements:
- Special cases:
- The file
/content/about/coverage-and-quality-report.html must include:
- At least 1
<p> element which contains the text Page last updated:
example
- Sourced from all
/content/patterns/**/examples/*.html files.
- Required elements:
<head><body><main>, which may include optional data-content-phase="experimental" attribute- An element with
aria-label="Related Links" containing:
- a
<ul> which has at least 1 <li> which has an a element containing the text "Related Issues"
- Special cases:
- There exists files at
content/shared/templates/example-usage-warning.html and content/shared/templates/experimental-example-usage-warning.html, which has the following:
exampleIndex
- Sourced from
/content/index/index.html.
- Required elements:
homepage
- Sourced from
/content/apg-home.html.
- Required elements:
- Expected id-defined sections:
- #top-card
- #resources
<h2><p>- 1 or more
<li> elements, each containing:
- #collaboration
<h2><p>- More than 1
<li> elements, each containing:
<h3><p><a> (not expected for the last <li>)<img>
htmlAsset
Serves a static .html file directly without any WAI related wrappers.
imageAsset
- Sourced from the following file types:
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.html files.
- 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 an examples-section class.
patternIndex
- Sourced from
/content/patterns/patterns.html.
- Required elements:
- Special cases:
- There exists a file at
content/shared/templates/read-this-first.html, which has the following:
practice
- Sourced from all
/content/practices/**/*-practice.html files.
- Required elements:
practiceIndex
- Sourced from
/content/practices/practices.html.
- Required elements:
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
/contentfolder./content/practices):/content/practices/practices.html/content/practicesshould have aSUBFOLDER_NAME-practice.htmlso the expected practice page is rendered. Eg./content/practices/landmark-regions/landmark-regions-practice.html/content/patterns):/content/patterns/patterns.html/content/patternsshould have aSUBFOLDER_NAME-pattern.htmlso the expected pattern page is rendered. Eg./content/patterns/alert/alert-pattern.html/content/patterns/SUBFOLDER_NAME/examples/*.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
/content/about/about.html.<head><body><h1><h2><main>containing:<ul>elementaboutPage
/content/about/**/*.htmlfiles.<head><body><h1><h2>/content/about/coverage-and-quality-report.htmlmust include:<p>element which contains the textPage last updated:example
/content/patterns/**/examples/*.htmlfiles.<head><body><main>, which may include optionaldata-content-phase="experimental"attributearia-label="Related Links"containing:<ul>which has at least 1<li>which has anaelement containing the text "Related Issues"content/shared/templates/example-usage-warning.htmlandcontent/shared/templates/experimental-example-usage-warning.html, which has the following:<body>exampleIndex
/content/index/index.html.<head><body><h1>homepage
/content/apg-home.html.<head><body><h1><p><a><img><h2><p><li>elements, each containing:<h3><p><a><img><h2><p><li>elements, each containing:<h3><p><a>(not expected for the last<li>)<img>htmlAsset
Serves a static
.htmlfile directly without any WAI related wrappers./scripts/pre-build/library/.tracked-html-assets.json.imageAsset
.svg.png.jpgotherAsset
Every other non-
.htmlfile (eg..js,.css)/content/shared/js/app.js./content/shared/js/skipto.js.pattern
/content/patterns/**/*-pattern.htmlfiles.<head><body><h1><section>elements:<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.patternIndex
/content/patterns/patterns.html.<head><body><h1>content/shared/templates/read-this-first.html, which has the following:<body>practice
/content/practices/**/*-practice.htmlfiles.<head><body><h1>practiceIndex
/content/practices/practices.html.<head><body><h1>