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

CWorking on an Existing Resource

Editing in GitHub

This method requires no setup and may be preferred by content authors. All file editing can be done int the GitHub Web App. Jus tNavigate toe the in the resource repo. Files can also be renamed and new files created.

The main disadvantage is each changed file will require its own separate commit. Also, the Netlify preview is regenerated for each commit, which can be slow.

Using a Local Development Environment

This provides faster edit-preview cycle and allows multiple file changes to be grouped into a single commit. It is also possible to use tooling like VS Code to give syntax highlighting, pretty printing, validation and more. However, does it require a little technical setup and possible familiarity with developer tooling. Develop working on aspects of the site beyond content will want to use the approach.

Note there are problems with running Jeckyll on Windows. And anyway, both the GitHub release workflow and the Netlify builds run on linux. So linux or Mac OS platform is really required. However, WSL on Windows is perfectly satisfactory for command line only access.

Get the Resource source code from GitHub

Use the command line or a graphical git client (GitHub for macOS/Windows, Sourcetree, Tower…) to clone the repository.

For the “Fundamentals Overview” repository, you would use the following command:

$ git clone git@github.com:w3c/wai-fundamentals-overview.git

The git URL is available by clicking the green ”Clone or download” button on the repository main page, for example: https://github.com/w3c/wai-fundamentals-overview

Install Use the Netlify CLI package

The netlify CLI package allows you to easily build and preview the resource locally.

Install and Initialize Jekyll

You can follow the official instructions but I found on WSL Ubuntu the most reliable (and flexible) method of installing Ruby and Jeckyll appears to be use rvm. Once Ruby, Jeckyll and bundle are setup:

Initializing Jekyll happens on the command line:

$ bundle install

Serve and preview the website

The easiest way (but without live reload) is:

$ netlify build && netlify dev

Alternatively, to preview changes, run the following command line program to start a local server

$ bundle exec jekyll serve --livereload

Use --incremental to only update the changed pages. This is useful for big repositories:

$ bundle exec jekyll serve --livereload --incremental

Manually Managing Submodules

The netlify CLI build command will initialise all submodules to the latest version on GitHub. The .gitmodules specifies which branch is ised for each and can be edited if you need to work on any submodule dependencies. This is the recommended way to work with submodules. However, you can manually manage when the submodules are refreshed fromGitHub.

From your graphical git client, you should be able to “Update all Submodules”.

This is how it works on the command line when you cloned the project for the first time:

$ git submodule update --init --recursive

This inits submodules in your local projects (creates the directories) and recursively fetches the data.

When you already have an existing clone (i.e. the second time on this machine) and want to get the latest version of all submodules, run:

$ git submodule update --remote

See also: Git - Submodules

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/.