Docs Build And Verify
Testing & Qualitydocs-build-and-verifyDocs Build And Verify is an Agent Skill for testing & quality published in the flet-dev/flet repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Use when asked to build, preview, or verify the Flet documentation website, including checking for broken links, broken images, and unresolved reST cross-references.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/flet-dev/flet/blob/HEAD/.agents/skills/docs-build-and-verify/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/docs-build-and-verify, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Docs Build and Verification
Prerequisites
Node.js 20 is required:
nvm use 20
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 automatically reports broken links and anchors. The build fails if any are found.
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.