Custom Routing

Use this guide when your React Router app defines routes manually instead of relying on the default file-based route convention.

When to Configure Routing

React Router's Framework Mode supports manually defined route definitions. When you use manual routes, QUI Docs can still discover MDX files, but it cannot infer the page URL from React Router's route config.

Add a routingStrategy so QUI Docs can map each discovered page file to the same URL React Router uses.

Example Routes

Assume that the app defines these route files:

src

routes

index.mdx

setup.mdx

help

contact-us.mdx

troubleshooting.mdx

The React Router route config can map those files explicitly:

// src/routes.ts
import {type RouteConfig, index, prefix, route} from "@react-router/dev/routes"

export default [
  index("routes/index.mdx"),
  route("setup", "routes/setup.mdx"),

  ...prefix("help", [
    route("contact-us", "routes/help/contact-us.mdx"),
    route("troubleshooting", "routes/help/troubleshooting.mdx"),
  ]),
] satisfies RouteConfig

Routing Strategy

In qui-docs.config.ts, provide a function that receives each file path relative to pageDirectory and returns the URL path segments for that file.

// qui-docs.config.ts
import {QuiDocsConfig} from "@qualcomm-ui/mdx-vite"

export default {
  // ...
  routingStrategy: (filePath: string) => {
    const routePath = filePath.replace(/\.(mdx|tsx)$/, "")
    const segments = routePath.split("/")

    if (segments.at(-1) === "index") {
      return segments.slice(0, -1)
    }

    return segments
  },
} satisfies QuiDocsConfig

The home route returns an empty array because it renders at /.

filePath	expected path segments
`index.mdx`	`[]`
`setup.mdx`	`["setup"]`
`help/contact-us.mdx`	`["help", "contact-us"]`
`help/troubleshooting.mdx`	`["help", "troubleshooting"]`

Keep Routes in Sync

The routingStrategy should describe the same URLs as routes.ts. If the React Router route config changes, update the strategy in the same PR so navigation, page links, breadcrumbs, and search results continue to point to the rendered page.

For the default file-based convention, omit routingStrategy and follow the naming rules in Page Configuration.

Last updated on May 29, 2026 by Ryan Bower