References And Includes

What "Reference" Means

Relevate uses references in a few different places. They look similar, but they are resolved at different times.

• Page references in docs.json point to source pages without file extensions.

• Navigation language labels can be translatable objects.

• Mintlify $ref values are resolved by the migration tool when importing a Mintlify project.

• OpenAPI references in frontmatter point to an operation, webhook, schema, or spec file.

This page explains each kind so a migrated project stays understandable after conversion.

Page References In Navigation

Most navigation entries are page references. They are strings that match files in your docs source folder without .md or .mdx.

{
  "navigation": {
    "tabs": [
      {
        "id": "docs",
        "label": "Docs",
        "content": [
          {
            "title": "Start",
            "pages": ["index", "quickstart", "guides/install"]
          }
        ]
      }
    ]
  }
}

This points to:

Do not include the source extension in navigation. Use guides/install, not guides/install.mdx.

Complex Page References

Use an object when a navigation item needs a custom sidebar title, icon, language filter, or version filter.

{
  "page": "guides/install",
  "title": "Install Relevate",
  "icon": "download"
}

When localization is enabled, title can be a translation map:

{
  "page": "guides/install",
  "title": {
    "en": "Install Relevate",
    "fr": "Installer Relevate",
    "nl": "Relevate installeren"
  }
}

The page itself can still have frontmatter. Navigation titles control the sidebar label; page frontmatter controls the page title, metadata, search title, and text exports.

Language References

Relevate's runtime language config is explicit:

{
  "navigation": {
    "languages": {
      "default": "en",
      "items": ["en", "fr", "nl", "jp"]
    }
  }
}

Default-language pages live at the root:

All translated pages share the same canonical page reference. Add only quickstart to navigation. Relevate uses the request locale and language config to resolve /fr/quickstart or /nl/quickstart.

Mintlify

Mintlify can split language navigation into separate JSON files:

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [
          {
            "tab": "Docs",
            "groups": [
              {
                "group": "Start",
                "pages": ["index", "quickstart"]
              }
            ]
          }
        ]
      },
      { "$ref": "./fr.json" },
      { "$ref": "./nl.json" }
    ]
  }
}

The Relevate importer reads those referenced files and folds them into a normal Relevate config. A referenced fr.json might look like this:

{
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Demarrage",
          "pages": ["fr/index", "fr/quickstart"]
        }
      ]
    }
  ]
}

The imported Relevate config becomes explicit:

{
  "navigation": {
    "languages": {
      "default": "en",
      "items": ["en", "fr", "nl"]
    },
    "tabs": [
      {
        "id": "docs",
        "label": {
          "en": "Docs",
          "fr": "Documentation"
        },
        "content": [
          {
            "title": {
              "en": "Start",
              "fr": "Demarrage"
            },
            "pages": ["index", "quickstart"]
          }
        ]
      }
    ]
  }
}

Why

Flattening imported $ref files has a few advantages:

• The generated docs.json is self-contained.

• Preview and production builds do not depend on additional JSON include files.

• Search, sitemap, sidebar generation, and language switching all see the same resolved navigation tree.

• The result is easier to review in a pull request because the final navigation is visible in one file.

If you prefer to keep source fragments for editing, keep them outside the production config and generate docs.json before build. Relevate expects the checked-in docs.json to be the resolved config.

OpenAPI Spec References

OpenAPI references are different from navigation $ref. They are strings that tell Relevate which OpenAPI spec and which operation or schema to render.

Configure one default OpenAPI spec:

{
  "openapi": "/openapi.json",
  "api": {
    "openapi": "openapi.json"
  }
}

Then reference operations in page frontmatter:

---
title: List users
openapi: "GET /users"
---

When a project has more than one spec, prefix the selector with the spec path:

---
title: List admin users
openapi: "admin-openapi.json GET /admin/users"
---

Remote spec URLs are also valid:

---
title: List users
openapi: "https://api.example.com/openapi.json GET /users"
---

Relevate normalizes HTTP methods, so get /users and GET /users resolve to the same operation.

Webhook References

Use webhook <name> to render a webhook from an OpenAPI document.

---
title: User created
api: "openapi.json webhook user.created"
---

api and openapi are both accepted for operation-style API pages. The importer may emit api for webhook pages because Mintlify commonly distinguishes API pages and webhooks in its source metadata.

Schema References

Use openapi-schema to render a component schema page.

---
title: User
openapi-schema: "openapi.json User"
---

You can also reference a schema from the default configured spec:

---
title: User
openapi-schema: "User"
---

Schema pages can include additional MDX below the generated schema.

---
title: User
openapi-schema: "openapi.json User"
---

<Info>
The `id` field is stable across environments.
</Info>

GraphQL Navigation Expansion

Add graphql to a content tab to generate a GraphQL reference from an SDL schema. Relevate expands that tab with Queries, Mutations, and Types groups.

{
  "id": "graphql",
  "label": "GraphQL API",
  "graphql": {
    "source": "schema.graphql",
    "directory": "graphql-reference"
  }
}

The short form uses the default graphql-reference directory:

{
  "id": "graphql",
  "label": "GraphQL API",
  "graphql": "schema.graphql"
}

The source can be a local file or an HTTPS URL. Generated operation pages include descriptions, arguments, return types, linked schema types, example operations, variables, sample responses, defaults, and deprecation reasons. Type pages document objects, interfaces, inputs, enums, unions, and custom scalars.

GraphQL tabs may contain existing groups, but not individual pages or other navigation nodes. Do not combine graphql with openapi or sdk on the same tab. Local schema changes are tracked during preview and rebuild the generated pages automatically.

OpenAPI Navigation Expansion

Navigation groups can reference an OpenAPI spec directly. Relevate expands the operations into generated pages during the build.

{
  "title": "API Reference",
  "openapi": {
    "source": "openapi.json",
    "directory": "reference"
  },
  "pages": []
}

An empty pages array means "include all visible operations from this spec." The generated pages use stable slugs under the configured directory.

You can also list specific operations:

{
  "title": "Users",
  "openapi": {
    "source": "openapi.json",
    "directory": "reference"
  },
  "pages": ["GET /users", "POST /users", "GET /users/{id}"]
}

Those selectors become generated page entries. Hidden operations are skipped.

Reference Resolution Order

When Relevate sees an OpenAPI reference, it resolves it in this order:

1. If the reference starts with a spec path or URL, use that spec.

2. Otherwise, use the configured api.openapi or top-level openapi.

3. Match operation selectors as METHOD /path.

4. Match webhook selectors as webhook name.

5. Match schema selectors from openapi-schema.

This means simple pages can use short selectors, while large projects can use explicit spec prefixes.

Best Practices

• Keep Relevate docs.json resolved and explicit.

• Use page references without .md or .mdx extensions.

• Use translation maps for labels instead of duplicating the whole navigation tree when possible.

• Let the Mintlify importer flatten $ref language files, then review the generated language labels.

• Prefix OpenAPI references with a spec file when multiple specs contain similar paths.

• Put generated OpenAPI pages under a stable directory such as reference.

• Keep hand-written API guidance below the generated frontmatter so the page remains portable.