WCAG 3
There is a presentation of the process the group uses for addressing issues and updates.
Editor's drafts of TR space documents are available at:
Make sure you have Node.js installed. This has primarily been tested with v20.
If you use fnm or nvm to manage multiple Node.js versions,
you can switch to the recommended version by typing fnm use or nvm use
(with no additional arguments) while in the repository directory.
First, run npm i in the root directory of the repository to install dependencies.
All commands are run from the root of the project, from a terminal:
| Command | Action |
|---|---|
npm start |
Start local dev server at localhost:4321 |
npm run build |
Build to ./dist/ |
npm run check |
Check for TypeScript errors |
npm run preview |
Preview build locally at localhost:4321 |
This repository uses Astro; see Astro's guide on project structure for standard directories.
Additional directories with special meaning:
guidelines/- contains content files which combine to form the normative documentacknowledgements/- Contents of Acknowledgement sections, one section per fileindex.json- Defines order of Acknowledgements sections
groups/- Contents of grouping sectionsindex.json- Defines order of grouping sections{group-name}.json- Defines order of underlying guideline sections; can specify status or title{group-name}/- Contents of Guideline sections{guideline-name}.md- Defines content of guideline and order of its requirements/assertions{guideline-name}/- Subdirectory containing requirements/assertions under each guideline{requirement-or-assertion-name}.md- Defines content of an individual requirement or assertion
terms/- Contents of terms defined in the Glossary
src/lib/- contains files that contribute to Astro build or template logicmarkdown/- contains files implementing remark and rehype plugins, to transform output of Markdown files
This section explains the fields available to frontmatter defined at the top of Markdown files for guidelines, requirements/assertions, and terms, and within JSON files for groups.
For those unfamiliar with the term, frontmatter refers to YAML written at the top of a file, surrounded on each side by a line consisting of 3 hyphens.
See existing files under the guidelines folder for examples.
These are available to multiple data types, as specified in each respective section below.
children- A list containing every slug found under a parent entry's corresponding subdirectory, in the order they are intended to be listed in the documenthowto- Optional boolean or string indicating the presence of a howto page for the given guideline or requirementtrueindicates the slug to reach the howto is consistent with the folder and filename of the current file- A string value indicates an exact slug
- This is likely to change when the howto documentation is revisited
status- Optional string: one of the status indicators outlined in the Explainer (in lowercase)title- Optional title of the guideline, requirement, or term- If unspecified, this will be derived from the slug, capitalizing the first letter of the first word and replacing hyphens with spaces
Represents each third-level heading that multiple guidelines are grouped under. Each group is defined in a JSON file, with its child guidelines located in a subdirectory with the same name.
- Supports common fields:
children,status - No additional unique fields
Represents each fourth-level heading that multiple requirements/assertions are listed under. Each guideline is defined in a Markdown file, with its child requirements/assertions located in a subdirectory with the same name.
- Supports common fields:
children,howto,status,title - No additional unique fields
Represents each fifth-level heading specifying an individual requirement or assertion.
- Supports common fields:
howto,status,title needsAdditionalResearch- Optional boolean, indicating whether to display a "needs additional research" editor's notetype- Optional string:foundational,supplemental, orassertion- If not specified, the entry will be rendered as "Requirement" (with neither "Foundational" nor "Supplemental" qualification)
Represents each dt/dd pair appearing in the Glossary section.
- Supports common fields:
status,title(these influence the content of thedtelement) synonyms- Optional list of other words or phrases that can be used to reference this term- This does not need to include plurals where the final word ends in "s" or "es"; this is automatically supported
Note: If a term file is empty, a "to be defined" Editor's Note will be inserted.
Definition lists can be specified directly in Markdown via the following format:
Term
: Definition
Another term
: Another definition
Shared term
Another shared term
: Shared definition
: Another shared definition
For more concrete examples, search for these directives in the repository.
The following block will be transformed into a decision tree details element,
with "Which foundational requirements apply" summary automatically included:
:::decision-tree
For each item:
1. Would X do Y?
- Yes, .... Stop.
- No, fail.
1. Would A do Z?
- ...
:::
The following block will be transformed into a yellow "Example" box:
:::example
Your content here
:::
The following block will be transformed into a green "Note" box:
:::note
Your content here
:::
The following block will be transformed into a green "Editor's Note" box:
:::ednote
Your content here
:::
The text inside :term[...] will be transformed into a link referencing a term in the glossary,
and can be used inline within blocks of text:
... is :term[programmatically determinable].
General notes:
- All instructions/examples in this section operate within the
guidelinesfolder - File and folder names should be in kebab-case (all lowercase, hyphen-delimited)
- See
titleunder Common Fields above regarding how entry names map to titles by default, and how to override with a custom title - Remember to add appropriate frontmatter; see the subsection under Supported Fields for the relevant entry type
- Other existing entries may be helpful to look at as examples, especially with regard to JSON or frontmatter syntax
For illustrative purposes, this refers to the new group as group-name.
To create a new top-level group:
- Under the
groupsfolder, create a subfolder for the new group (e.g.groups/group-name) - Also under the
groupsfolder (not the new subfolder), create a JSON file with the same basename as the new subfolder (e.g.groups/group-name.json), with the following content:{ "children": [ ] } - Edit
index.json(directory under the top-levelguidelinesfolder) to add an entry in itschildrenarray for the new group (again using the same basename, e.g.group-name)- This is what makes the group appear in the document structure, and determines its order among the other top-level groups
- Follow the instructions below to create at least one guideline within the group, and at least one requirement or assertion within each guideline
For illustrative purposes, this refers to the existing parent group as group-name
and the new child guideline as guideline-name.
To create a new guideline:
- Under the desired group's folder, create a subfolder for the guideline
(e.g.
groups/group-name/guideline-name) - Edit the JSON file for the group (e.g.
groups/group-name.json) to add an entry in itschildrenarray for the new guideline (again using the same basename, e.g.guideline-name)- This is what makes the guideline appear in the document structure, and determines its order among the other guidelines under the same group
- Also under the group's folder (not the new subfolder),
create a Markdown file with the same basename as the new subfolder
(e.g.
groups/group-name/guideline-name.md)- To prevent the build from failing before any requirements or assertions are added,
include the following initial content:
We will expand
--- children: [] --- @@ add guideline text herechildrento a multi-line list when adding requirements/assertions. Note that including some content after the frontmatter is also necessary for the build to function.
- To prevent the build from failing before any requirements or assertions are added,
include the following initial content:
- Follow the instructions below to create at least one requirement or assertion within the guideline
For illustrative purposes, this refers to the existing parent guideline as guideline-name,
its parent group as group-name, and the new child requirement as requirement-name.
Note that the process is the same for requirements or assertions; the only difference is
the value of type in the entry's frontmatter
(see Fields for Requirements and Assertions).
- Under the desired guideline's folder, create a Markdown file
(e.g.
groups/group-name/guideline-name/requirement-name.md) - Edit the Markdown file for the guideline (e.g.
groups/group-name/guideline-name.md) to add an entry in itschildrenarray for the new guideline- This is what makes the requirement/assertion appear in the document structure, and determines its order among the other entries under the same guideline
- Arrays in frontmatter can be expressed similarly to Markdown lists, e.g.:
--- children: - requirement-name ---
Creating a glossary term is more straightforward, since there is no hierarchy:
create a Markdown file under terms, then populate its content and any applicable
frontmatter.
Filters build output to reduce noise when diffing output between changes. This is for maintenance purposes only, to catch regressions; built code is not expected to run properly when this is active!
Default: Unset (set to any non-empty value to enable)