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.
- verify resource repository and files
- review page frontmatter and config.yml
- note designated ‘publication’ branch of the resource
- ensure a mergable PR to the publication branch with working Netlify preview
- merge the PR in GitHub
- add resource’s GitHub repo to wai-website submodules list
- pull the submodule code into the wai-website
- create symlinks to integrate the new content into wai-website
- update the config.yml file to include the new resource.
- check wai-website preview looks good
- push wai-website
- release wai website
- check deployment
In the following
wai-resource is a placeholder for the resource name - eg
Verify resource repository and files
- The git hub repository is
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
- content/ - Jekyll page source with frontmatter
- filesystem organisation is not important as Jekyll spiders
- target URI is in frontmatter
- content-images/wai-resource/ - static image assets
- target URI is /content-images/wai-resource/
- content-assets/wai-resource/ - other static assets
- target URI is /content-assets/wai-resource/
- _includes/wai-resource - Jekyll includes
- _layouts - Jekyll layouts
- _collections - Jekyll collections
- _plugins - ruby plugins for liquid
- _data/wai-resource - Jekyll data files
- Gemfile - may include resource specific Gems
- config.yml - Jekyll config
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: firstname.lastname@example.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/.
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.
cd _pages ln -s ../_external/resources/wai-wcag-supplemental/content/ wai-wcag-supplemental
Then check with
$ wai-wcag-supplemental -> ../_external/resources/wai-wcag-supplemental/content/
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
Just copy the section contents eg
collections: patterns: title: Patterns permalink: /WCAG2/supplemental/:collection/:name/ output: true sort_by: ref
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
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.
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.
Check the WAI website is correctly updated.
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