Skip to content

Setup and Run

This page explains how to set up and run the uxi-landing demo site in a development environment.

Prerequisites

  • Node.js 18+ and npm (for the Next.js app)
  • Python 3.8+ and pip (for the mkdocs documentation site)
  • Git (to clone or pull the repository)

Setup: Next.js Demo Site

The main UXI landing demo is a Next.js application located at uxi-landing/.

1. Install Dependencies

From the uxi-landing root:

cd uxi-landing
npm install

2. Run the Development Server

npm run dev

The demo site will be served at http://localhost:3000 by default.

  • Homepage: http://localhost:3000/
  • Mobility page: http://localhost:3000/mobility

3. Build for Production (Optional)

npm run build
npm start

This creates an optimized production build and serves it.

Setup: MkDocs Documentation Site

The documentation for the UXI architecture and implementation is built using mkdocs with the mkdocs-template package.

1. Install Python Dependencies

From the uxi-landing root:

pip install -r requirements.txt

This installs: - mkdocs - mkdocs-material - pymdown-extensions

Additionally, install the mkdocs-template package (local editable install from the monorepo):

cd ../mkdocs-template
pip install -e .
cd ../uxi-landing

2. Run the Documentation Server

Use the custom KRR (Kill, Rebuild, Restart) command:

mkdocs-oves-krr

This will: - Kill any existing processes on port 8000 - Clean build artifacts - Build the mkdocs site - Start the server

The documentation site will be available at http://127.0.0.1:8000.

Alternatively, to run without KRR:

mkdocs serve

3. Build Static Documentation (Optional)

mkdocs build

Static HTML files will be generated in site/.

What You'll See

Next.js Demo (localhost:3000)

  • Homepage: UXI blocks demonstrating hero, feature grids, stats strip, story timeline, and CTA.
  • Mobility page: Same UXI blocks configured for mobility use case, with a Cloudinary background video.
  • All content driven by JSON in content/pages/home.json and content/pages/mobility.json.

MkDocs Documentation (localhost:8000)

  • Home: Overview of the UXI Landing repo.
  • UXI Architecture: Full architectural blueprint from the uxi-architecture.md file.
  • Implementation: How the repo implements the UXI pattern (blocks, media registry, JSON-driven pages).
  • Footer displays version, editor, revision summary, and date as configured in mkdocs.yml.

Troubleshooting

  • Port conflicts: If port 3000 or 8000 is in use, stop the conflicting process or change the port in Next.js (package.json scripts) or mkdocs config.
  • Missing dependencies: Re-run npm install or pip install -r requirements.txt.
  • Template overrides not loading: Ensure mkdocs-template is installed (pip install -e ../mkdocs-template) and mkdocs.yml references the correct custom_dir.