Migrate from deprecated @hanzo/mdx + @hanzo/ui to the new
@hanzo/docs (16.4.1), @hanzo/docs-mdx (14.2.8), and
@hanzo/docs-ui (16.5.3) package stack. Update all import paths
to use correct subpath exports and switch CLI from hanzo-mdx
to docs-mdx.
Consolidate to single @hanzo/docs package with subpath exports:
- @hanzo/docs/core/* for core functionality
- @hanzo/docs/ui/* for UI components
- @hanzo/docs/mdx/* for MDX processing
Uses hanzo-docs CLI instead of fumadocs-mdx for build commands.
Use Hanzo's own documentation framework fork for better integration
with existing @hanzo/ui components and consistent theming.
- Replace fumadocs-core with @hanzo/docs-core
- Replace fumadocs-ui with @hanzo/docs-ui
- Replace fumadocs-mdx with @hanzo/docs-mdx
BREAKING CHANGE: Package paths have been reorganized for clarity
## Major Changes
### Package Structure
- Collapsed engine/core â engine (removed unnecessary nesting)
- Moved core/types â types (top-level types package)
- Added root facade for single-import experience
- Removed redundant factory.go
### SDK Improvements
All SDKs now provide single-import interfaces:
- Go: import "github.com/luxfi/consensus"
- Python: import lux_consensus as consensus
- Rust: use lux_consensus::*
### Documentation
- Added comprehensive introduction and architecture docs
- Created AI/ML integration guide for researchers
- Added research section with papers and experiments
- Improved sidebar organization and discoverability
### Benefits
- Shallow, obvious import paths
- One responsibility per package
- DRY, composable, orthogonal design
- Idiomatic patterns for each language
- Consistent API across all SDKs
This refactor provides a clean, intuitive developer experience where
one import is enough and things work one way only.
- Added missing SDK pages to staticPages array: python, rust, cpp, mlx
- Fixed MDX parsing errors in cpp.mdx and rust.mdx:
* Wrapped function signatures containing HTML-like syntax in backticks
* Fixed <uint16_t>, <const>, Result<()> being interpreted as HTML tags
- All SDK pages now generate correctly and are accessible
- Verified mlx.html, python.html, rust.html, cpp.html, go.html, c.html all build
Fixes: /docs/sdk/mlx returning 404
Add comprehensive SDK documentation for all supported languages:
- Python SDK: Cython bindings with asyncio support
- Rust SDK: Safe FFI bindings with zero-cost abstractions
- C++ SDK: Modern C++20 with optional MLX GPU acceleration
- MLX GPU: Apple Silicon acceleration guide (up to 25x speedup)
Updated sidebar navigation to include all SDK pages.
All SDKs provide:
- Installation instructions
- API reference with examples
- Performance benchmarks
- Testing guidelines
- Troubleshooting tips
Test coverage:
- Go tests: All passing â
- Docs build: Success â
- Create local Logo component with Lux triangle SVG
- Remove @luxfi/logo dependency to fix CI build
- Update pnpm-lock.yaml
- Logo uses currentColor for proper dark mode support
- Import fumadocs-ui/style.css for proper layout and components
- Add @luxfi/logo package and use Logo component in nav
- Set sidebar to pure black (#000) for both light and dark modes
- Update semantic color tokens for better consistency
- Replace lucide Zap icon with official Lux triangle logo
- Ready to be forked as template for other Lux protocol docs
- Add complete CSS variable system for light/dark themes
- Add semantic color tokens (background, foreground, primary, etc.)
- Add Lux brand theme with cyan/blue accent colors
- Improve layout with proper font variables and structure
- Add metadata for better SEO
- Use OKLCH color space for modern color management
- Create proper homepage for static export
- Add meta refresh to auto-redirect to documentation
- Includes fallback link for manual navigation
This fixes the 404 error on the root path.
- Fix circular dependency in fumadocs loader causing build hang
- Replace loader with direct MDX imports for static generation
- Add static page tree to avoid runtime dependencies
- Configure basePath for GitHub Pages (/consensus)
- Add .nojekyll file to prevent Jekyll processing
- Update GitHub Actions workflow to deploy to Pages
- Add out/ directory to .gitignore
All 8 pages now generate successfully as static HTML (SSG).
Build completes in ~2 seconds. Ready for GitHub Pages deployment.
- Removed @hanzo/ui dependency (peer dependency conflicts)
- Upgraded fumadocs-core, fumadocs-mdx, fumadocs-ui to v16
- Upgraded tailwindcss to v4.1.17
- Converted Tailwind config to CSS-based @theme syntax for v4
- Fixed generateStaticParams API for fumadocs-mdx v12+
Note: Build still hangs at "Creating an optimized production build" phase.
This appears to be a Turbopack issue with Next.js 16. Investigation ongoing.
Related: Updated @hanzo/ui peer dependencies to support Next 16 and React 19
(changes in ~/work/hanzo/ui/pkg/ui/package.json - not committed here)
Fixed the fumadocs-mdx v12 API compatibility issue by updating
generateStaticParams to use the correct docs.getPages() method
instead of the non-existent docs.generateParams().
The build now starts successfully, though it's taking longer than
expected (4+ minutes at "Creating an optimized production build" phase).
Updated DOCS_STATUS.md to track progress and document the situation.
zeekay