You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: 11ty/README.md
+89-2Lines changed: 89 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ XSLT-based build process using Eleventy.
8
8
Make sure you have Node.js installed. This has primarily been tested with v20,
9
9
the current LTS at time of writing.
10
10
11
-
If you use [fnm](https://github.com/Schniz/fnm) or [nvm](https://github.com/nvm-sh/nvm) to manage multiple Node.js versions,
11
+
If you use [`fnm`](https://github.com/Schniz/fnm) or [`nvm`](https://github.com/nvm-sh/nvm) to manage multiple Node.js versions,
12
12
you can switch to the recommended version by typing `fnm use` or `nvm use`
13
13
(with no additional arguments) while in the repository directory.
14
14
@@ -23,11 +23,96 @@ Common tasks:
23
23
-http://localhost:8080/techniques
24
24
-http://localhost:8080/understanding
25
25
26
-
Maintenance tasks (for working with Eleventy config and supporting files under this subdirectory):
26
+
Maintenance tasks (for working with Eleventy config and supporting files used by the build):
27
27
28
28
-`npm run check` checks for TypeScript errors
29
29
-`npm run fmt` formats all TypeScript files
30
30
31
+
## Publishing to WAI website
32
+
33
+
The following npm scripts can be used to assist with publishing updates to the WAI website:
34
+
35
+
-`npm run publish-w3c` to publish 2.2
36
+
-`npm run publish-w3c:21` to publish 2.1
37
+
38
+
Each of these scripts performs the following steps:
39
+
40
+
1. Updates the data used for the Techniques Change Log page
41
+
- Note that this step may result in changes to `techniques/changelog.11tydata.json`, which should be committed to `main`
42
+
2. Runs the build for the appropriate WCAG version, generating pages and `wcag.json` under `_site`
43
+
3. Copies the built files from `_site` to the CVS checkout (see [`WCAG_CVSDIR`](#wcag_cvsdir))
44
+
45
+
## Associated Techniques Data
46
+
47
+
Each success criterion's page contains a Techniques section which links to associated techniques.
48
+
These used to be defined directly in HTML in each respective page, but have since been relocated to
49
+
a single data file, `understanding/understanding.11tydata.js`, under the key `associatedTechniques`.
50
+
51
+
This field is typed, in order to provide some degree of autocomplete in IDEs that support TypeScript
52
+
(e.g. Visual Studio Code), as well as some amount of immediate feedback while editing.
53
+
Further validation is performed when running the build or dev server, to provide more focused error messages for common mistakes.
54
+
55
+
### Listing Techniques
56
+
57
+
Techniques may be indicated via an object as outlined below, or using a shorthand string.
58
+
Shorthand strings may function as either `id` or `title` seen below, and are
59
+
recommended for brevity when no `using` or `and` relationship is present.
60
+
61
+
The following list outlines properties available on each technique object:
62
+
63
+
-`id` - Technique ID
64
+
-`title` - Technique description (HTML flow content allowed), to define free-form entries that don't reference a specific technique
65
+
-`using` - Optional array of further techniques to be populated into a child list
66
+
- Child techniques may also include `using`
67
+
-`usingConjunction` - When `using` is specified, this overrides the word that appears before `usingQuantity`
68
+
- Default: `"using"`; HTML flow content allowed
69
+
-`usingQuantity` - When `using` is specified, this overrides the word that appears after `usingConjunction` and before "of the following techniques"
70
+
- Default: `"one"`
71
+
- May be empty string (`""`), in which case the subsequent "of" is dropped
72
+
-`usingPrefix` - Adds text to appear before `usingConjunction`
73
+
-`skipUsingPhrase` - Omits the entire "... using ... of the following techniques" phrase
74
+
- This is mainly an escape hatch for rare instances where a child list is used but no "using" phrase appears at all (e.g. in 1.4.4: Resize Text)
75
+
76
+
Typically, either `id` or `title` is required.
77
+
If `id` is specified, then `prefix` and/or `suffix` may also be specified (with HTML flow content allowed in each),
78
+
resulting in "{prefix} {linked technique title} {suffix}".
79
+
80
+
In extremely rare cases, `using` may be specified alone without either `id` or `title`,
81
+
e.g. for top-level "Using two or more of the following" in 2.4.5: Multiple Ways.
82
+
83
+
#### Conjunctions
84
+
85
+
To represent multiple parallel techniques, an `and` key may be specified instead of `id` or `title`. In this case, the following properties are supported:
86
+
87
+
-`and` - an array of technique objects or shorthand strings (as described above)
88
+
-`using` and its related fields (seen above) may optionally be specified alongside `and`
89
+
-`andConjunction` may optionally be specified alongside `and`,
90
+
to override the default `"<strong>AND</strong>"` phrasing (e.g. in 4.1.3: Status Messages)
91
+
- Techniques listed _within_`and` should be flat, never containing `and` or `using`
92
+
93
+
### Situations or Other Subsections (Sufficient only)
94
+
95
+
The top level of the `sufficient` array may consist entirely of either technique entries (see above)
96
+
or subsection entries. It should not contain a mix of both.
97
+
98
+
Subsections are typically used to define multiple "situations", where each title begins with "Situation A:", "Situation B:", etc.;
99
+
in rare cases it is used for other purposes, e.g. in 1.4.8: Visual Presentation.
100
+
101
+
Subsection entries contain the following:
102
+
103
+
-`title` (required, HTML allowed)
104
+
-`techniques` (required) - array of technique entries (see above)
105
+
-`note` (optional, HTML allowed) - content to appear in a Note at the end of the subsection (e.g. in 4.1.3: Status Messages)
106
+
-`groups` (optional) - array of objects with `id`, `title`, `techniques`; see more below
107
+
-`techniques` within `groups` are not expected to involve `and` or `using`
108
+
109
+
#### Groups within Situations
110
+
111
+
Most of the situations in 1.1.1: Non-text Content include groupings which start with a boldface paragraph (not a heading),
112
+
and are referenced one or more times within preceding "using" clauses.
113
+
Groups can be defined at the top level of each situation/section entry as mentioned above.
114
+
Defining `groups` automatically implies a "using" relationship, without explicitly defining `using` for each technique.
115
+
31
116
## Environment Variables
32
117
33
118
### `WCAG_CVSDIR`
@@ -98,6 +183,8 @@ Generates `_site/wcag.json`. (This is not done by default, as it adds to build t
98
183
99
184
**Default:** Unset by default; `publish-w3c` scripts set this to a non-empty value.
100
185
186
+
For more information on the output, see [11ty/json/README.md](json#readme).
187
+
101
188
### `GITHUB_REPOSITORY`
102
189
103
190
**Usage context:** Automatically set during GitHub workflows; should not need to be set manually
0 commit comments