Docs Build and Verification

Prerequisites

Node.js 24 is required, matching what CI runs:

nvm use 24

Build

Full production build (includes broken link detection):

cd website && yarn build

Dev server with hot reload:

cd website && yarn start

Regenerate API data and sidebars only (no Docusaurus build):

cd website && yarn crocodocs:generate

Check Broken Links

yarn build reports both, but only broken links fail the build. Docusaurus defaults onBrokenAnchors to warn and docusaurus.config.js does not override it, so a broken anchor scrolls past in the log and still ships - grep the build output for Broken anchor rather than trusting the exit code.

Check Broken Images

Run this after yarn build to find images referenced in HTML that don't exist:

cd website && python3 -c "
import re, os, glob

build_dir = 'build'
img_re = re.compile(r'<img[^>]+src=\"(/[^\"]+)\"', re.IGNORECASE)
broken = []

for html_file in sorted(glob.glob(f'{build_dir}/docs/**/index.html', recursive=True)):
    page = html_file.replace(build_dir + '/', '').replace('/index.html', '')
    content = open(html_file).read()
    for match in img_re.finditer(content):
        src = match.group(1)
        if src.startswith('http') or src.startswith('data:'):
            continue
        file_path = os.path.join(build_dir, src.lstrip('/'))
        if not os.path.exists(file_path):
            broken.append((page, src))

if broken:
    print(f'Found {len(broken)} broken images:')
    for page, src in broken:
        print(f'  {page}: {src}')
else:
    print('No broken images found!')
"

Check Unresolved reST Cross-References

After building, check for reST roles that failed to resolve and appear as raw text:

cd website && grep -r ':attr:\|:class:\|:meth:\|:func:' build/docs/ --include='*.html' -l

If any files are listed, those pages have unresolved cross-references that render as plain text instead of links.