Troubleshooting

The site is served under a path, but Clay built it for the root. Set baseURL to that path, with slashes on both sides:

baseURL: "/my-project/"

Check it with npx clay preview: it serves the site under its baseURL, like the host does.

Reference images relative to the page, like img/screen.png or ../img/screen.png. Paths starting with / point to the root of the domain, not to your docs, and break under a baseURL. npx clay build reports images that do not exist.

Clay reads the dates from git. Either the docs are not in a git repository, or CI checked out only the last commit.

- uses: actions/checkout@v7
  with:
    fetch-depth: 0

variables:
  GIT_DEPTH: 0

• Check the icon’s classes on fontawesome.com: both the style and the name are needed, fa-solid fa-rocket.
• Pro icons only work with a kit that includes them.
• With a kit, add your site’s domain to the kit’s allowed domains in your Font Awesome account.

The site needs a web server: opened from disk (file://…), the browser cannot load its styles, scripts and search. Use npx clay preview.

Clay shows which page failed and why. Common causes:

• A link in raw HTML points to a page that does not exist. The link check only sees Markdown links; fix the HTML link.
• Front matter is not closed: the second --- line is missing.

Run npx clay build --verbose for the complete output.

A build and the dev server cannot run in the same project at the same time. Stop clay dev (Ctrl + C in its terminal), then build again.

clay dev reloads the browser when a page, an image or clay.yaml changes. If nothing happens, check that you edit the files of the project clay dev was started in, and look at its output for errors.

Another program uses port 3000 (or 4173 for clay preview). Choose another one:

npx clay dev --port 3001

Clay needs Node.js 20.19 or newer. Check with node --version, and update Node.js from nodejs.org or with your version manager.