Visual diff

Get a list of documentation files that changed between the pull request and the latest version of the documentation, and see their differences highlighted visually on the documentation pages.

While seeing changes in source files is helpful, it can be difficult to understand how those changes will look in the rendered documentation, or their impact on the documentation as a whole. Read the Docs makes it easy to see the changes in the rendered documentation.

Show diff menu in preview

To enable or disable this feature for your project:

  1. Go the Settings tab of your project.

  2. Click on Addons, and click on Visual diff.

  3. Check or uncheck the Enable visual diff option.

  4. Click on Save.

When enabled, a new UI element appears at the top right of the page showing a dropdown selector containing all the files that have changed in that pull request build.

_images/screenshot-viz-diff-ui.png

You can select any of those files from the dropdown to jump directly into that page. Once there, you can toggle Visual Diff on and off by pressing the Show diff link from the UI element, or pressing the d key if you have hotkeys enabled.

Visual diff shows all the sections that have changed, highlighting their differences with red/green background colors. You can jump between each of these chunks by clinking on the up/down arrows.

Show build overview in pull requests

Note

This feature is only available for projects connected to a GitHub App.

To enable or disable this feature for your project:

  1. Go the Settings tab of your project.

  2. Click on Pull request builds.

  3. Check or uncheck the Show build overview in a comment option.

  4. Click on Update.

When enabled, a comment is added to the pull request when changes are detected between the pull request and the latest version of the documentation.

_images/build-overview-comment.png

General settings

Ignored files

You can configure a list of files or patterns to be ignored when listing the files that changed in the pull request. This is useful when you have files that have a date in them, or listing/archive files that show changes without content changes in those files.

  1. Go the Settings tab of your project.

  2. Click on Addons, and click on File tree diff.

  3. In the Ignored files field, add one or more patterns to ignore, one per line.

  4. Click on Save.

Patterns are matched against the relative paths of the HTML files produced by the build, you should try to match index.html, not docs/index.rst, nor /en/latest/index.html. Patterns can include one or more of the following special characters:

  • * matches everything, including slashes.

  • ? matches any single character.

  • [seq] matches any character in seq.

Base version

The base version is the version of the documentation that is used to compare against the pull request. By default, this is the latest version of the documentation. This is useful if your latest version doesn’t point the default branch of your repository.

Note

This option can be changed by contacting Site support.

How main content is detected

The visual diff compares the “main content” of HTML pages, ignoring headers, footers, navigation, and other page elements that aren’t part of the documentation content itself. This helps avoid false positives, like all pages being marked as changed because of a date or commit hash being updated in the footer.

For details on how the main content area is detected, see Detection logic.

Tip

If the heuristic root element picked by Visual Diff is wrong for your project theme, set the CSS main content selector under Settings > Addons. Visual Diff honors this override; other features like Server Side Search do not.

Limitations and known issues

  • The diff considers HTML files only.

  • The diff is done between the files from the latest successful build of the pull request and the default base version (latest by default). If your pull request gets out of sync with its base branch, the diff may not be accurate, and may show unrelated files and sections as changed.

  • Invisible changes. Some sections may be highlighted as changed, even when they haven’t actually visually changed. This can happen when the underlying HTML changes without a corresponding visual change, for example, if a link’s URL is updated

  • Tables may be shown to have changes when they have not actually changed. This is due to subtle variations in how HTML tables are rendered, and will be fixed in a future version.

  • The background of diff chunks may be incorrect when we are unable to detect the correct main parent element for the chunk.