Step 1: Create a new repository
Use GitHub to create a new repository using the WAI resource template.
- Go to this GitHub page: github.com/new
w3c/wai-resource-templatein the ‘Repository template’ section
- Type a name of the repository starting with
wai-(usually we use just lowercase letters but sometimes we use camel case)
- Set the visibility setting to ‘Public’
- Click ‘Create repository’ button
A new GitHub repository should be created with the name you selected.
Step 2: Configure your new repository
Step 2.1 Create a new branch for your work
Make the configurations in a branch first, and merge that branch with the new configurations into the main branch only once you have tested them in later the steps.
To create a branch in your newly created GitHub repository:
Codetab (below the repository name)
- Click the branch button (has a branch symbol, the text ‘main’ or ‘master’, and a down triangle)
- Type a new branch name in the search box and hit enter
The branch button should now have the name of the branch you created.
Step 2.2 Update placeholder references
Several placeholder references in the newly created repository need to be updated, to reflect your repository name. Make these changes in your newly created branch rather than in the main branch.
Replace the text
wai-resource-template with the name of your new repository in the following files:
- config.yaml (line 13)
- config.yaml (line 32)
- README.md (line 1)
- content/index.md (line 22)
In content/index.md update:
- lines with “# NEW” comments
Step 2.3 Update the images location
Your newly created repository has a folder called
/content-images/wai-resource-template/, which also needs to change to your repository name. Also make this change in your newly created branch first.
To change the folder name:
- Go to the file called
.gitignorein the folder called
- Click the edit button (a pencil symbol)
- Go to the text field with the text
.gitignore(above the ‘Edit file’ pane)
- Replace the text
../your-repository-name/.gitignore(using your actual repository name in place of
- Click ‘Commit changes’ button (towards the bottom of the page)
You should now have a folder called
/content-images/your-repository-name/ in your repository (where
your-repository-name is your actual repository name).
Step 2.4: Set permissions (Settings, Manage access)
- From the action list (starting with Code, Issues,…), select “Settings” (at the end).
- From the secondary list (after Options), select “Manage access”.
- Select the button “Invite teams or people”.
- Set the appropriate permissions. Err on the side of lower-level access for starters; we can change it easily. Example permissions:
- w3c/wai-eo : Read
- non-Team editors : Triage (or Write if highly trusted)
Step 3: Create and link a Netlify site for preview
Netlify allows you to preview the content, including draft content in branches, as it would look when it is deployed on the WAI website. To configure such Netlify previews for your repository:
- Login into Netlify site page
- Make sure
W3C Teamis selected top left, rather than your own personal team (ask to be added to the team if required)
- Click ‘New site from Git’ button
- Click ‘GitHub’ button
- Authenticate to GitHub, select ‘w3c’ organization
- Type your repository name into the search box and hit enter
- Click on your repository name in the search results
- Click ‘Deploy Site’ button
- Click ‘Site settings’ button
- In ‘General - Site details’ (you should be taken there), click ‘Change site name’ button and enter your repo name
- In ‘Build & deploy’, scroll down to ‘Post processing - Form detection’, click ‘Edit settings’ button, uncheck ‘Run form detection’, and click ‘Save’ button
To view the resource preview
- Click on ‘Deploys’ in top navigation bar
- You should get the message ‘Production: master@HEAD Published’ - wait for the deploy to complete if the message is other than ‘Published’
- Click on ‘Production’ to get to the preview
Step 4: Create your content
You will almost certaily want to develop and preview locally though it is possible to use the GitHub file editor. You can use use a Linux/Mac shell, or WSL on Windows.
NOTE: In order to facilitate sharing and review with others use a GitHub PR for your work. Mark it is “Draft”. When it is ready to publish on the WAI website, coordinate with Shawn or other website maintainer, as described below.
Content in the main branch is assumed ready to be deployed on the WAI website. Therefore, create a new branch for your draft content — for example: “Version 1”. You can follow Step 2.1 to create a new branch. When you create the pull request (to see the preview), create it as a “Draft pull request”.
Put your content in the folder called
content, and images in the folder
content-images/your-repository-name/. Your new repository has an initial file called
content/index.md, which you can use as a template. This file has frontmatter many configuration parameters that you need to set for every new file that you create. It also has different styles and functionality that you can reuse.
In particular, replace the text
/link/to/page/ (on lines 24 and 32) in every file with the path of where your page will appear on the WAI website (you may not know this at the beginning of the project and you can do it later too). Also update the mappings in the file
netlify.toml (on line 10) when you are ready.
Also, update the README.md text to remove the template specific lines below the netlify badge, and to provide documentation.
Local preview of your content
The easiest way to build and preview locally is to use the Netlify CLI tool. The resources are configured so you can
Netlify build- generate the website file in the
Netlify dev- run a dev server and preview
Editing shared config files
The theme and other shared config files in
wai-website-theme are accessed via git submodules located in
_external. While it is certainly possible to use git submodule operation to locally edit these while developing, this is complex and to be honest, a dangerous ‘footgun’.
For some files it is possible to create a temporary local
_collections folder to overide theme files or add new ones. When the resource is ready to be published these files should be merged into the shared files in
Publishing approved content
When the content is approved for publication, change the pull request from “draft” to “ready to review” and inform Shawn or or other WAI site maintainer (usually best to assign in GitHub and send e-mail).
Shawn or other WAI site maintainer will:
- Merge into the main branch.
- Go to the GitHub Add Resource Workflow for the wai-website and click the ‘Run workflow’ Button. Enter the repository name - eg.
wai-about-waiand click ‘Run workflow’’ again. Wait for the Workflow to complete.
- Add the resource to
navigation.ymlper the instructions.