Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

docs: add MDX link checker script and fix broken quickstart link

f-trycuae208446be564
diff --git a/docs/content/docs/cua/reference/cli-playbook/commands.mdx b/docs/content/docs/cua/reference/cli-playbook/commands.mdx
index 8b2ef4017b..61bcc7dd4c 100644
--- a/docs/content/docs/cua/reference/cli-playbook/commands.mdx
+++ b/docs/content/docs/cua/reference/cli-playbook/commands.mdx
@@ -428,6 +428,6 @@ watch -n 5 cua list
## Next Steps
-- [Get started with the quickstart guide](/get-started/quickstart#cli-quickstart)
+- [Get started with the quickstart guide](/cua/guide/get-started/what-is-cua)
- [Learn about Cua computers](/cua/reference/computer-sdk)
- [Explore agent automation](/cua/guide/fundamentals/agent-loops)
diff --git a/docs/scripts/check-mdx-links.py b/docs/scripts/check-mdx-links.py
new file mode 100755
index 0000000000..68dbbf7296
--- /dev/null
+++ b/docs/scripts/check-mdx-links.py
@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+"""
+MDX Link Checker - Checks for broken internal links in MDX files.
+
+This script scans MDX files in the docs/content/docs directory and validates
+that all internal links point to existing files.
+
+Usage:
+ python scripts/check-mdx-links.py [docs_dir]
+
+Example:
+ python scripts/check-mdx-links.py
+ python scripts/check-mdx-links.py /path/to/docs/content/docs
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+from collections import defaultdict
+
+
+def find_mdx_files(docs_dir: Path) -> list[Path]:
+ """Find all MDX files in the docs directory."""
+ return list(docs_dir.rglob("*.mdx"))
+
+
+def extract_links(content: str) -> list[tuple[str, int]]:
+ """Extract all internal links from MDX content with line numbers."""
+ links = []
+
+ # Markdown links: [text](/path) or [text](/path#anchor)
+ md_link_pattern = r'\[([^\]]*)\]\((/[^)#\s]+)(?:#[^)]*)?\)'
+
+ # JSX href attributes: href="/path" or href='/path'
+ jsx_href_pattern = r'href=["\'](/[^"\'#\s]+)(?:#[^"\']*)?["\']'
+
+ lines = content.split('\n')
+ for line_num, line in enumerate(lines, 1):
+ # Find markdown links
+ for match in re.finditer(md_link_pattern, line):
+ links.append((match.group(2), line_num))
+
+ # Find JSX href attributes
+ for match in re.finditer(jsx_href_pattern, line):
+ links.append((match.group(1), line_num))
+
+ return links
+
+
+def normalize_link_to_file_path(link: str, docs_dir: Path, public_dir: Path) -> tuple[Path | None, str]:
+ """Convert an internal link to a file path. Returns (path, type)."""
+ # Skip external links and anchors
+ if link.startswith(('http://', 'https://', 'mailto:', 'tel:', '#')):
+ return None, 'external'
+
+ # Remove leading slash
+ clean_link = link.lstrip('/')
+
+ # Check if it's a public asset (images, etc.)
+ if clean_link.startswith(('img/', '_next/', 'favicon')):
+ return public_dir / clean_link, 'public'
+
+ # Skip links that go outside docs (like /get-started which doesn't exist)
+ if not clean_link.startswith(('cua/', 'cuabench/')):
+ # These are likely old/invalid paths
+ return docs_dir / clean_link, 'docs'
+
+ # Build the file path
+ file_path = docs_dir / clean_link
+
+ return file_path, 'docs'
+
+
+def check_file_exists(file_path: Path) -> bool:
+ """Check if a file exists (with or without .mdx extension, or as index.mdx)."""
+ # Direct match
+ if file_path.exists():
+ return True
+
+ # Try with .mdx extension
+ mdx_path = file_path.with_suffix('.mdx')
+ if mdx_path.exists():
+ return True
+
+ # Try as directory with index.mdx
+ index_path = file_path / 'index.mdx'
+ if index_path.exists():
+ return True
+
+ # Try parent directory with filename.mdx (for paths like /cua/guide)
+ parent_index = file_path.parent / (file_path.name + '.mdx')
+ if parent_index.exists():
+ return True
+
+ return False
+
+
+def check_links(docs_dir: Path, public_dir: Path) -> dict[str, list[tuple[str, int, str]]]:
+ """Check all links in MDX files and return broken ones."""
+ broken_links = defaultdict(list)
+
+ mdx_files = find_mdx_files(docs_dir)
+
+ print(f"\nπŸ” Scanning {len(mdx_files)} MDX files in {docs_dir}\n")
+ print("-" * 60)
+
+ for mdx_file in mdx_files:
+ try:
+ content = mdx_file.read_text(encoding='utf-8')
+ except Exception as e:
+ print(f"⚠️ Error reading {mdx_file}: {e}")
+ continue
+
+ links = extract_links(content)
+
+ for link, line_num in links:
+ # Skip external links
+ if link.startswith(('http://', 'https://', 'mailto:', 'tel:')):
+ continue
+
+ # Skip anchor-only links
+ if link.startswith('#'):
+ continue
+
+ file_path, link_type = normalize_link_to_file_path(link, docs_dir, public_dir)
+ if file_path is None:
+ continue
+
+ if not check_file_exists(file_path):
+ rel_file = mdx_file.relative_to(docs_dir)
+ broken_links[str(rel_file)].append((link, line_num, str(file_path)))
+
+ return broken_links
+
+
+def main():
+ # Determine docs directory
+ if len(sys.argv) > 1:
+ docs_dir = Path(sys.argv[1])
+ else:
+ # Default: look for docs/content/docs relative to script location
+ script_dir = Path(__file__).parent
+ docs_dir = script_dir.parent / 'content' / 'docs'
+
+ # Public directory for static assets
+ public_dir = docs_dir.parent.parent / 'public'
+
+ if not docs_dir.exists():
+ print(f"❌ Directory not found: {docs_dir}")
+ sys.exit(1)
+
+ broken_links = check_links(docs_dir, public_dir)
+
+ # Summary
+ print("\n" + "=" * 60)
+
+ total_broken = sum(len(links) for links in broken_links.values())
+ files_with_broken = len(broken_links)
+
+ print(f"\nπŸ“Š Summary:")
+ print(f" Files with broken links: {files_with_broken}")
+ print(f" Total broken links: {total_broken}")
+
+ if broken_links:
+ print(f"\n❌ Broken Links:\n")
+
+ for file_path, links in sorted(broken_links.items()):
+ print(f" πŸ“„ {file_path}")
+ for link, line_num, target_path in links:
+ print(f" Line {line_num}: {link}")
+ print(f" β†’ Expected: {target_path}")
+ print()
+
+ # Suggest fixes for common patterns
+ print("\nπŸ’‘ Common issues to check:")
+ print(" - Links starting with /docs/ should NOT have /docs/ prefix")
+ print(" - Internal links should start with /cua/ or /cuabench/")
+ print(" - Check if the target file was renamed or moved")
+ print()
+
+ return 1
+ else:
+ print("\nβœ… All internal links are valid!\n")
+ return 0
+
+
+if __name__ == '__main__':
+ sys.exit(main())
diff --git a/docs/src/app/global.css b/docs/src/app/global.css
index da2be8918c..ab16f39f90 100644
--- a/docs/src/app/global.css
+++ b/docs/src/app/global.css
@@ -41,13 +41,8 @@
overflow-x: hidden;
}
-/* Ensure search dialog appears above fixed header (z-50) */
-[data-search-dialog],
-[data-radix-dialog-content][role="dialog"],
-[vaul-drawer] {
- z-index: 100 !important;
+/* Push search dialog below the fixed header on mobile */
+[data-radix-dialog-content] {
+ top: 4rem !important;
}
-[data-radix-dialog-overlay] {
- z-index: 99 !important;
-}
diff --git a/docs/src/components/custom-header.tsx b/docs/src/components/custom-header.tsx
index 8e7558ac07..79bacae66f 100644
--- a/docs/src/components/custom-header.tsx
+++ b/docs/src/components/custom-header.tsx
@@ -48,7 +48,8 @@ const docsSites = [
dropdownIconHeight: 18,
navTabs: [
{ name: 'Guide', href: '/cuabench/guide/getting-started/introduction', prefix: '/cuabench/guide' },
- { name: 'Reference', href: '/cuabench/reference/cli-reference', prefix: '/cuabench/reference' },
+ { name: 'Examples', href: '/cuabench/guide/examples/custom-agent', prefix: '/cuabench/guide/examples' },
+ { name: 'API Reference', href: '/cuabench/reference/cli-reference', prefix: '/cuabench/reference' },
],
},
];
@@ -76,7 +77,7 @@ export function CustomHeader() {
}, []);
return (
- <header className="fixed top-0 left-0 right-0 z-50 border-b border-fd-border bg-fd-background/80 backdrop-blur-sm">
+ <header className="fixed top-0 left-0 right-0 z-40 border-b border-fd-border bg-fd-background/80 backdrop-blur-sm">
<div className="container mx-auto flex h-14 items-center justify-between px-4">
{/* Left: Logo and Nav */}
<div className="flex items-center gap-6">