Portal Architecture#

The VEX Developer Portal is built as a highly automated "Truth Engine." Instead of manually maintaining duplicate documentation, the portal pulls directly from the source code and design documents in the core VEX repositories.

🏗️ The Technology Stack#

• Framework: Next.js (App Router)
• Content: MDX (via next-mdx-remote)
• Styling: Tailwind CSS
• Code Highlighting: Shiki (High-fidelity syntax highlighting)
• Deployment: Railway + Nixpacks

🔄 Documentation Synchronization#

The heart of the portal is the sync-docs.js script. This script runs during the prebuild phase and performs the following tasks:

1. Repository Management#

If the build environment (local or CI) doesn't have sibling folders for vex or vex-halt, the script automatically clones them into a temporary .repos/ directory.

2. Truth Extraction#

• Architecture: Syncs ARCHITECTURE.md into /docs/guides/architecture.
• Roadmap: Syncs ROADMAP.md into /docs/roadmap.
• Benchmarks: Syncs vex-halt/README.md into /docs/benchmarks.
• Changelog: Parses the standard GitHub CHANGELOG.md and transforms it into rich MDX with typed version badges (feature, fix, security, breaking).

3. API Reference Generation#

The script triggers cargo doc --workspace within the VEX repository. The generated HTML is then:

• Copied into the portal's /public/rustdoc folder.
• Injected: We inject a custom rustdoc-custom.css and a "Back to Docs" navigation banner directly into the Rustdoc HTML files.

🛡️ MDX Hardening#

To prevent the portal from crashing during build due to invalid MDX (like naked < characters in technical descriptions), the sync-docs.js script includes an escapeMdx function. This function automatically escapes common MDX pitfalls while preserving valid React components like <Callout /> or <VersionBadge />.

🛤️ Deployment Workflow#

The portal is optimized for Railway's Nixpacks builder.

1. Setup: Nixpacks installs the Node, Rust, Cargo, and Git binaries defined in nixpacks.toml.
2. Pre-build: The documentation is synchronized and hardened.
3. Build: Next.js generates the static pages.
4. Deploy: The site is served with low-latency global edge caching.

🛠️ Adding New Docs#

To sync a new file from a remote repository:

1. Open scripts/sync-docs.js.
2. Locate the synchronization blocks (e.g., // Automate Architecture Sync).
3. Add a new block specifying the source path and the target src/content path.
4. If the new content contains many mathematical or logic symbols, ensure they are passed through escapeMdx.