Creating a PR: Building and previewing documents

Document build

You can build the understanding and technique documents locally.

The main spec is done separately (with Respec), this is only for the informative docs.

Eleventy Process (introduced July 2024)

See https://github.com/w3c/wcag/tree/main/11ty#usage for full instructions on installation and running.

The short version:

1. Install Node.js (preferably v20, the current LTS)
2. Run npm i in the root of the repository
3. Run npm start for a local development server, or npm run build to generate all files under _site

Ant Process (deprecated)

This build process is now superseded by the Eleventy process above.

Installing

There are two methods of installing the appropriate software:

1. Raw install

Firsly install Java.

Then install Apache Ant and make sure it works. Help page for MacOS

E.g. typing at the command-line: # ant -version Should show version info.

2. Homebrew (Mac OS specific)

1. Install homebrew
2. Install OpenJDK
3. Install ant

Building the documents

From the base WCAG directory (the one containing build.xml) type "ant -projecthelp" to get a list of commands you can run. E.g., ant understanding generates the Understanding, and ant techniques generates the Techniques. It will generate them into the "output" directory, plus some intermediate files a few other places.

You can type ant clean to remove stray build files. It will overwrite a couple files from the repository; normally you shouldn't commit, instead type git reset --hard after ant clean.

That should cover most of what you might need to do with the generator.

Creating previews of Informative Docs

If you have a PR for understanding or technique document, the best way to create a preview is:

1. Copy the branch name from the PR.

2. Go the main code page, and use the branch name to filter to the branch you need.

3. Navigated through the code files to find the correct file. E.g. Understanding > 2.2 > dragging-movements.html

4. Copy the URL of that page.

5. Go to https://raw.githack.com/ and put the URL into the top box.

6. Copy the URL from the "Use this URL for development" box.

7. Use that URL for the preview.