Added the glossary page by G0dwin · Pull Request #53 · act-rules/act-tools

G0dwin · 2026-03-31T15:42:01Z

Adds the tools necessary to generate a glossary page and add it to the nav.

Dependent PR in act-rules to be published shortly.

Note: much of this was generated using Co-pilot, be on the lookout for code that doesn't meet standards.

Because we probably will not be able to preview this until after we merge the packages, I have a preview available on my personal site here.

Related PR: act-rules/act-rules.github.io#2395

daniel-montalvo

Hi @G0dwin .

thanks for putting this together.

I think the act-tools repo should be the place to have this conversation, as this is were the logic lives.

I have a couple of thoughts based on previous work, especially act-rules/act-rules.github.io#2377 and w3c/wcag-act-rules#387

The URIs we settled on for these examples were: /act/rules/terms/accessible-name/examples/

This is because on the WAI website we have the pattern that every URI needs to be meaningful in itself.

If we include this work as-is, we would leave /act/rules/terms/ with no meaningful content, and we would be adding yet another pattern /act/rules/glossary/ which wouldn't meet user expectations.

I propose we rename /act-rules/glossary/ to /act/rules/terms/, just to avoid having two patterns repeated throughout.

In addition, I'd request review from @remibetin because these code updates are intended to push content to the WAI website, so he needs to be aware as the WAI website maintainer.

G0dwin · 2026-04-06T15:26:20Z

Hi @G0dwin .

thanks for putting this together.

I think the act-tools repo should be the place to have this conversation, as this is were the logic lives.

I have a couple of thoughts based on previous work, especially act-rules/act-rules.github.io#2377 and w3c/wcag-act-rules#387

The URIs we settled on for these examples were: /act/rules/terms/accessible-name/examples/

This is because on the WAI website we have the pattern that every URI needs to be meaningful in itself.

If we include this work as-is, we would leave /act/rules/terms/ with no meaningful content, and we would be adding yet another pattern /act/rules/glossary/ which wouldn't meet user expectations.

I propose we rename /act-rules/glossary/ to /act/rules/terms/, just to avoid having two patterns repeated throughout.

In addition, I'd request review from @remibetin because these code updates are intended to push content to the WAI website, so he needs to be aware as the WAI website maintainer.

Thanks Daniel, I updated the URL and committed the change. You can preview it here.

remibetin · 2026-04-14T13:37:26Z

Thanks @daniel-montalvo and @G0dwin. I'll review the use of the WAI theme, and I've asked @kfranqueiro if he could review the Typescript updates. We plan to coordinate next week on this.

remibetin

Hi @G0dwin,

Thanks for your work on this. I've started the review and added some suggestions and questions.

To help with the review, I'm interested in more information on who the glossary page is intended for, and examples of use cases. AFAIK, each rule already includes a list of glossary terms with their definition. Will there be links to the glossary page somewhere else?

I also think the scope and purpose of the glossary page is important to convey to the end-users. For example, users may wonder how this relates to section 4.12 Glossary of ACT Rules Format 1.1. To that end, I suggest adding a "Summary" box at the top that provide this information. I can help refine the wording.

cc @daniel-montalvo @kfranqueiro

remibetin · 2026-04-21T10:08:45Z

+    lines.push("### Used in rules");
+
+    const rules = [...(usedInRules.get(key) || new Set())].sort((a, b) =>
+      a.id.localeCompare(b.id),
+    );
+    if (rules.length === 0) {
+      lines.push("- None");
+    } else {
+      rules.forEach((rule) => {
+        lines.push(
+          `- [${rule.name}](/standards-guidelines/act/rules/${rule.id}/proposed/)`,
+        );
+      });
+    }


The "Used in Rules" list can become quite big and require a lot of scrolling from users. For example, the list for the "Outcome" term consists of 94 items.

Before considering possible solutions, could you clarify who this section is intended for?

I agree, this adds a large amount of visual space. I think embedding this content in summary and details elements is probably the best solution but I that would be assuming use cases myself. This came from the issue requirements:

In scope: New glossary index (and/or per-term pages), navigation entry, working anchors and links on WAI, “used in rules” lists with correct WAI rule URLs, full definition bodies as above.

I think it may also be a good option to move forward with the page as it is and adjust this later if it holds us up.

@WilcoFiers , do you have any context or suggestions to add here?

Co-authored-by: Rémi Bétin <github@remibetin.fr>

WilcoFiers

Looks good. Couple nitpicks.

WilcoFiers · 2026-04-29T12:44:53Z

Would you mind adding some tests for this?

Tests for src/utils/glossary.ts were added in commit 6aa3ade, covering getGlossaryHeading, normalizeHeadingLevels, and getGlossaryBody (both rule and full modes).

WilcoFiers · 2026-04-29T12:50:57Z

+export const getFullGlossary = (glossary: DefinitionPage[]): string => {
+  const glossaryTexts = glossary.map(getFullGlossaryMarkdown);
+  return joinStrings(`## Glossary`, ...glossaryTexts);
+};


Are getFullGlossary and getFullGlossaryMarkdown just for testing? Seems unnecessary if that's the case. If we want to test the mode of getGlossaryBody we should test that function directly.

Great catch, I'll remove it.

getFullGlossary and getFullGlossaryMarkdown were removed in commit 6aa3ade.

G0dwin · 2026-04-30T22:47:05Z

@copilot resolve the merge conflicts in this pull request

Co-authored-by: G0dwin <1109252+G0dwin@users.noreply.github.com>

Copilot · 2026-04-30T22:50:16Z

@copilot resolve the merge conflicts in this pull request

Resolved the merge conflict with origin/main in commit 0b17c67. The conflict was in yarn.lock due to the pre-commit → @fastify/pre-commit change on main. The lockfile was regenerated and all 270 tests pass.

Added the glossary page

69f4051

G0dwin mentioned this pull request Mar 31, 2026

Added the glossary page act-rules/act-rules.github.io#2395

Open

G0dwin self-assigned this Mar 31, 2026

G0dwin requested review from Jym77, WilcoFiers and daniel-montalvo March 31, 2026 15:43

Fixed an issue with the Glossary nav link

d8787e6

daniel-montalvo requested changes Apr 3, 2026

View reviewed changes

Updated URL

31cfb5a

Reused code between get-glossary and generate-glossary

1f3b836

remibetin suggested changes Apr 28, 2026

View reviewed changes

G0dwin and others added 5 commits April 28, 2026 15:13

Update src/cli/generate-glossary.ts

d6387cc

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

91f0816

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

82f624f

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

61dea9c

Co-authored-by: Rémi Bétin <github@remibetin.fr>

Update src/cli/generate-glossary.ts

037816c

Co-authored-by: Rémi Bétin <github@remibetin.fr>

WilcoFiers requested changes Apr 29, 2026

View reviewed changes

Removed unused function and added tests

6aa3ade

Copilot started work on behalf of G0dwin April 30, 2026 22:47 View session

Merge origin/main into feature/glossary - resolve yarn.lock conflict

0b17c67

Co-authored-by: G0dwin <1109252+G0dwin@users.noreply.github.com>

Copilot finished work on behalf of G0dwin April 30, 2026 22:51

Conversation

G0dwin commented Mar 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

daniel-montalvo left a comment

Choose a reason for hiding this comment

Uh oh!

G0dwin commented Apr 6, 2026

Uh oh!

remibetin commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

remibetin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

remibetin Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

G0dwin Apr 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

WilcoFiers left a comment

Choose a reason for hiding this comment

Uh oh!

WilcoFiers Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

G0dwin Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

WilcoFiers Apr 29, 2026

Choose a reason for hiding this comment

Uh oh!

G0dwin Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

G0dwin commented Apr 30, 2026

Uh oh!

Copilot AI commented Apr 30, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

G0dwin commented Mar 31, 2026 •

edited

Loading

remibetin commented Apr 14, 2026 •

edited

Loading