This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.

Integrating a Resource

As described in Architecture, Builds and Deployments the modular WAI website architecture adds considerable complexity to a typical Jekyll built website. In particular, git submodules and filesystem symbolic links are used to ensure Jekyll finds all files needed to build the site. This in turn, places requirements on file layout in both individual resources and the wai website. Additionally, some parts of the Jekyll config for each resource are copied over to the wai website Jekyll config.

Resources are created using a template which helps ensure the file layout is correct. However editors are unlikely to understand all the constraints so may make changes which can be incompatible and need correcting for successful integration.

Overview of Integration Steps

The following outlines the steps for integrating a new resource. Updating an existing resource may require a subset of these steps depending on what changes have been made.

Note: in general it is easiest to perform all this work locally, working on both the resource and wai-website code using Netlify CLI to preview. However it is probably possible to do most steps using the GitHub web app and Netlify console (the exception being managing symlinks which require a *nix Shell).

Note: The following steps work directly on the wai-website main branch and resource designated ‘publication’ branch. It may well be preferable to work on temporary branches for both before merging to commit to the changes ready for the release. This requires fiddling with the submodule config but is fairly straight forward.

  1. verify resource repository and files
  2. review page frontmatter and config.yml
  3. note designated ‘publication’ branch of the resource
  4. ensure a mergable PR to the publication branch with working Netlify preview
  5. merge the PR in GitHub
  6. add resource’s GitHub repo to wai-website submodules list
  7. pull the submodule code into the wai-website
  8. create symlinks to integrate the new content into wai-website
  9. update the config.yml file to include the new resource.
  10. check wai-website preview looks good
  11. push wai-website
  12. release wai website
  13. check deployment

In the following wai-resource is a placeholder for the resource name - eg wai-course-list

Verify resource repository and files

These are the folders and files required for integration, some are optional. Note many assets are shared and so accessed via the wai-website-theme or _data submodule resources. Those found here are resource specific

NB: The files that are direct children of _data must all be links to the included wai-website-data git submodule files. Otherwise resource specific changes have been made and will be lost in integration. Currently these are:

Review page frontmatter and config.yml

Minimal frontmatter is as follows.

title: .....
permalink: /.../...
feedbackmail: wai@w3.org
github:
  repository: w3c/wai-resource
  branch: main
  path: content/filename
footer: ...

The config.yml file is mostly template but some sections will need to be copied to the wai-website config.file, with slight modification. See below.

Note designated ‘publication’ branch of the resource

The workflow dictates that one git branch will be the publication branch. The content of this branch will appear in the wai-website when it is built. Critically, this is the branch used by the git submodule command.

Check carefully as this may or may not be the GitHub ‘default’ branch.

Ensure a mergable PR to the publication branch with working Netlify preview

The workflow is PR based so there should be a open PR attempting to merge changes onto the publication branch. The integrated Netlify Preview should have been used to confirm the content renders correctly. It is possible to access GitHub PRs locally via git but as it’s slightly fiddly the working preview for the PR is preferable.

All the above checks should pass in the PR.

Merge the PR in GitHub

Merge in GitHub means the production branch is up to date ready for the git submodule access. The wai-website preview and publication will then access it.

Add resource’s GitHub repo to wai-website submodules list

The wai-website file .gitmodules lists each resource submodule’s repositry URL on GitHub and the branch. However, the new resource can’t be added by just editing the file. A git command needs to be run:

git submodule add -b production-branch https://github.com/w3c/wai-resource.git _external/resources/wai-resource

Confirm by inspecting the tail of ‘gitmodules’ file.

[submodule "_external/resources/wai-resource"]
	path = _external/resources/wai-resource
	url = https://github.com/w3c/wai-resource
	branch = master

Pull the submodule code into the wai-website

If the submodule already existed the following will update all submodules code held in wai-website

git submodule update --init --remote

Check the code now exists at ‘_external/resources/wai-resource/.

You should git pull too to get the latest code as usual.

Create symlinks to integrate the new content into wai-website

The process is to cd to the directories that will hold the link and then “ln -s” to the target file/directory under “_external”. The various folders are listed above. If the resource has the directory you will need to link it.

For example:

cd _pages
ln -s ../_external/resources/wai-wcag-supplemental/content/ wai-wcag-supplemental

Then check with ls -l:

$ wai-wcag-supplemental -> ../_external/resources/wai-wcag-supplemental/content/

and ls wai-wcg-supplemental will show the resource files in it’s content folder.

Note: links under “pages” link to the resource’s “content/” folder. Thus file changes in the resource do not require link updates to wai-website. Some old links are done per file which makes maintenance a headache.

Update the config.yml file to include the new resource

config.yml is mostly template but the following sections will need to be copied, with slight modification

Collections

Just copy the section contents eg

collections:
  patterns:
    title: Patterns
    permalink: /WCAG2/supplemental/:collection/:name/
    output: true
    sort_by: ref

Defaults

The issue is that in the resource the config is for the entire website, where as in the wai-website it becomes one sub part. So for example:

defaults:
  - scope:
      path: ""
    values:
      layout: standalone_resource
      standalone_resource_header:
        title: Supplemental Guidance to WCAG 2

becomes

defaults:
    scope:
      path: "pages/wai-wcag-supplemental"
    values:
      layout: standalone_resource
      standalone_resource_header:
        title: Supplemental Guidance to WCAG 2

Check wai-website preview looks good

You can of course do a local build and preview of the wai-website using the Netlify CLI (with ntl build && ntl dev).

The Netlify preview for the entire wai-website will also build when the new master branch contents are pushed to GitHub (see below). It is also possible to manually trigger a build on Netlify at anytime.

See the wai-website deploys page.

Note: that with Lighthouse scores enabled in Netlify the build takes a long time to load.

Fix any problems found in the preview. Remember some change will need to be made in the resource repo and others in the wai-website repo. Ensure everything gets pushed to GitHub.

Push wai-website

git add .
git commit -m"Integrate wai-resource resource"
git push

Release wai website

In GitHub create a new release which runs GitHub action to build the site and deploys it via GitHub pages and a W3C site redirect.

https://github.com/w3c/wai-website/releases

Check deployment

Check the WAI website is correctly updated.

https://www.w3.org/WAI/

Note: sometimes new pages DO NOT appear when the should. The current theory is indeterminate delays in the GitHub publication to pages mean the final w3c publish step doesn’t see the new pages. If this occurs then wait and then run publish.

Back to Top

This is an unpublished draft preview that might include content that is not yet approved. The published website is at w3.org/WAI/.