Configuring Vale and HTML tests

This page helps you customise the Vale and HTML tests that run in the CI/CD pipeline.

Configuring Vale validation

Your new project repository already includes a basic Vale validation config, but to use Vale in this project, you must download a package of the approved 3di Vale rules – see Adding or updating the 3di Vale rules.

For more information on other things you can do with Vale, see Using Vale.

Configuring the HTML tests

HTML tests run after the site is built. They check the generated pages in build/ for problems such as broken internal links. Configure them in .htmltest.yml at the project root.

When this check is enabled, a failed HTML test stops preview publishing so broken in-site links are not released to a preview URL.

info

To disable the GitLab htmltest job, or to let it fail without blocking the pipeline, see CI pipeline guide.

Updating the YAML file

To customise the settings for this job, edit the YAML file. For the list of settings, see the table below.

1. In your Git client or editor, open .htmltest.yml at the project root.
2. Change the required settings.
3. Keep list items under IgnoreURLs aligned with the existing entries.
4. Commit and push. If the changes are correct, the next pipeline uses your updated file.

Default settings

.htmltest.yml

DirectoryPath: build
IgnoreURLs:
  - ^https?://localhost
  - ^https?://127\.0\.0\.1
IgnoreInternalEmptyHash: true
IgnoreEmptyHref: true
IgnoreCanonicalBrokenLinks: false
IgnoreAltMissing: true
IgnoreDirectoryMissingTrailingSlash: true
CheckExternal: false

Setting	Description	Typical choice
DirectoryPath	The folder htmltest scans. Must match Docusaurus output.	Leave as build.
IgnoreURLs	URL patterns that are not treated as failures.	Keep localhost; add customer URLs that are not live yet. For more information, see the section below.
CheckExternal	Whether to fetch live internet links. This is slower and can fail when a third-party site is down.	Keep false unless you need to check externals in CI.
IgnoreAltMissing	Missing or empty alt on images. Empty alt="" is valid for decorative images.	Keep true so decorative icons do not fail the pipeline
IgnoreCanonicalBrokenLinks	Canonical URL metadata that doesn't match a real page.	Keep false so real link issues still fail.
IgnoreDirectoryMissingTrailingSlash	Folder URLs with or without a trailing /.	Keep true for Docusaurus.

Ignore URLs

Use this when a link is intentional but the target is not a real page yet, for example a placeholder customer site, a ticket URL, or a staging host.

1. Under IgnoreURLs:, add a new dashed line.
2. Use a pattern that matches the start of the URL.

Example — ignore a customer site that is not published:

IgnoreURLs:
  - ^https?://localhost
  - ^https?://127\.0\.0\.1
  - ^https://docs.example.com

warning

Only ignore URLs that are placeholders. Ignoring too much hides broken links that authors should fix.

Checking external links

By default the test doesn't call the public internet (CheckExternal: false). That keeps pipelines fast and avoids failures when an unrelated website is down.

To check external links:

1. Set CheckExternal: true.
2. Optionally, raise ExternalTimeout if slow sites time out. The template sets this to 10 seconds.

Keep external checks off for day-to-day authoring. Turn them on for a release pass if the project has many outbound links that must stay valid.

Checking image alternative text

This template turns off alt checks (IgnoreAltMissing: true) because the site includes decorative icons with empty alt="", and htmltest fails those by default.

htmltest distinguishes two cases:

Setting	Default	What it allows
IgnoreAltMissing	false	Images with no alt attribute
IgnoreAltEmpty	false	Decorative images with alt=""

To enforce alt text while still allowing decorative images:

1. Set IgnoreAltMissing: false (fail when alt is absent).
2. Set IgnoreAltEmpty: true (allow empty alt="" for decorative images).
3. Tell authors that meaningful pictures need a short alt description, and that purely decorative pictures use alt="".

If you leave IgnoreAltEmpty at false, empty alts fail the pipeline even though they are valid for accessibility.

Next steps

• Customise the CI/CD pipeline — turn Vale or HTML tests off, or make Vale blocking
• Getting started — run the site locally and confirm links before you push