Routing Conventions

Private folders

In directory-group mode, a plain folder whose name begins with _ is private. QUI Docs skips every route file inside it. Use private folders for demos, components, fixtures, and other files that support a page without creating pages of their own.

The private-folder rule does not apply to a folder containing +, such as _public+. The route manifest treats _public+ as a pathless group, but the QUI Docs page map retains _public in indexed URLs. Do not use an underscore-plus folder for indexed MDX pages.

Flat filenames

Dots in a route filename create URL segments. Route nesting uses the longest matching route filename as the parent layout.

about.index.jsx and about._index.jsx are alternative names for the same index route. Use one of them, not both.

Layouts and parent overrides

A route becomes a layout when another route has a matching filename prefix. The layout component must render an outlet for its child routes.

A leading underscore creates a pathless segment. The segment still determines layout nesting but does not appear in the URL.

Append an underscore to a segment to keep the URL segment while opting out of the matching parent layout:

Dynamic and optional segments

A segment beginning with $ creates a dynamic parameter. A bare $ creates a splat that matches the remaining URL. Parentheses make a static or dynamic segment optional.

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:

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 /.

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.