website_diff is a utility that compares two HTML websites, and outputs a diff as a third HTML website.
The diff site has insertion/deletion highlighting, automatic scroll-to-next and scroll-to-previous key bindings,
image diffing, and highlighting of links pointing to diffed pages.
This tool is primarily meant to help see/find differences in websites that are automatically generated from some source documents (e.g. documentation pages, Jupyterbooks, etc) that may not be obvious from source diffs produced by GitHub. This is particularly useful when the source documents run code whose output may silently change, even though the source files remain constant.
Ensure Rust and Cargo are installed. Instructions can be found here.
You may also need to install the cairo library if your distribution does not include it.
pip install --upgrade pip
pip install website_diff
website_diff takes as an input two folders each containing an index.html file, as well as the name of a third folder to be created
that will contain the diffed website.
website_diff --old path/to/old/site/ --new path/to/new/site/ --diff path/where/diff/site/will/be/created
If website_diff runs successfully, the diff website will be available at
path/where/diff/site/will/be/created/index.html
To access the command line interface help documentation, run
website_diff --help
website_diff can be used as part of a GitHub Actions workflow that runs when a website source code repository is updated.
See the example workflow in .github/workflow-templates/example_workflow.yml. In this example, the workflow:
- Checks out the website repository on the PR branch
- Builds the PR website
- Commits the PR website to the
gh-pagesbranch - Checks out the
gh-pagesbranch - Builds the diff website using
website_diff - Commits the diff website to the
gh-pagesbranch - Posts a message on the PR thread pointing users to each website
This example template is based on a real usage of website_diff in the Introduction to Data Science online textbook repository here: https://github.com/UBC-DSCI/introduction-to-datascience-python/blob/main/.github/workflows/deploy_pr_preview.yml
- Text: Diffs are highlighted in green if text was inserted, and red if text was deleted.
- Links to pages with diffs: Any links that point to a page containing diffs are yellow.
- Images: New images have a green border and are highlighted in green, deleted images have a red border and are highlighted in red, and changed images are outlined in yellow with differences highlighted in red.
- When first opening a page with diffs, the browser will scroll to the first diff on the page
- To scroll to the next off-page diff, press the n key
- To scroll to the previous off-page diff, press Shift+n or N
There are several examples that can demonstrate the kinds of differences that website_diff will detect. To run website_diff on those examples, simply run the bash script run_tests.sh found within the website_diff repo. The run_tests.sh script pulls the examples from a separate repo called website_diff_examples. The folder website_diff_examples/examples will then contain several folders each representing a different example e.g. lines of text changed, image added, page added, etc. In each of those folders, there will be an old and prerendered_old folder for the old website and old website with pre-rendered figures, new and prerendered_new for the new website and new website with pre-rendered figures, and lastly diff for the diffed version of the website with an index.html file that shows everything that has changed between the old and new versions of the website.