Running Checks

Testing catches broken links, missing information, and layout problems before visitors see them. Run commands from the root of your local Website repository.

Automated checks

Run these commands one at a time. Wait for each to finish successfully before starting the next.

1. Build the website

bundle exec jekyll build

This creates a local copy of the finished website in _site/.

2. Check generated pages and links

bundle exec htmlproofer ./_site --disable-external --ignore-urls '/minecraft:/'

This checks the finished pages and links between PWindows pages. It does not contact external websites.

3. Check PWindows-specific rules

bundle exec ruby tools/verify-site.rb ./_site

This checks public addresses, page headings, descriptions, sitemaps, required data fields, matching pages, images, shared links, and files that must not be published. It also checks every configured language route, localized data fields, article language folders, document languages, and the single root sitemap.

4. Check JavaScript when needed

If assets/js/main.js changed:

node --check assets/js/main.js

5. Check the final diff

git diff --check

Then use git status and git diff to confirm that only intended files changed.

Manual browser checks

Automated checks cannot judge every visual or interaction problem. Preview affected pages and confirm:

• there is no sideways scrolling;
• text and headings are readable;
• links and images are correct;
• keyboard focus is visible and follows a sensible order;
• changed controls work with keyboard, mouse, and touch;
• reduced-motion behavior still works;
• phone, tablet, and desktop layouts look correct;
• footer columns stack at 540px and below.

For localization changes, also confirm:

• / works without redirecting to /en-us/;
• _site/en-us/ was not generated;
• the equivalent /zh-cn/ pages exist;
• the language switcher preserves the current page;
• only the root sitemap.xml and robots.txt were generated.

If a command fails

Read the first useful error, correct the related file, and run that command again. One small mistake may produce several messages, so fix the earliest clear cause first.

Common messages:

• Missing generated route: an expected page was not created. Check its permalink, layout, and source file.
• Unexpected canonical URL: the official page address is wrong. Check the permalink and url in _config.yml.
• Sitemap mismatch: check that the page address is intentional and that /sitemap includes it.
• Missing asset: make sure the image or other file exists under assets/ and its path begins with /.
• Unknown article author: use an existing key from _data/staff.yml.
• Department mismatch: make the department key, page setting, permalink, and data path agree.

Ask a maintainer for help if you cannot identify the cause. Do not alter unrelated files just to make an error disappear.

Next: Deployment