Skip to content
Getting Started

Configuration

Reference for every rdx.config.ts option, including accepted values, defaults, and links to detailed guides.

Minimal configuration

Edit rdx.config.ts at your project root:

ts
import { defineConfig } from '@lexibase/rdx'

export default defineConfig({
  metadata: {
    applicationName: 'My documentation',
  },
})

Only metadata.applicationName is required. It provides the default browser title, the page-title suffix, social preview defaults, footer branding, and the built-in homepage name. For example, a page named Installation appears in the browser as Installation | My documentation.

Use navbar.title for optional text beside the navbar logo.

The footer shows the site name and a Powered by RDX link to the framework's GitHub repository. Set metadata.since to the project's or organization's starting year. The CLI fills this with the year the project is created; you can edit it:

ts
metadata: {
  applicationName: 'My documentation',
  since: 2004,
},

An earlier starting year produces a range, such as 2004–2026. Equal years are shown once. Omitting since shows only the current year. Use a positive whole year no later than the current year.

Common options

The defaults below apply when you omit a field. The starter created by the CLI sets some fields explicitly, including the theme toggle and the GitHub action.

OptionAccepted valueDefaultWhat it controls
metadataObject with applicationNameRequiredSite identity and metadata
descriptionString''Default site description for metadata and the built-in homepage
langLanguage tag string, such as en or pt-BRenHTML language and built-in labels. See Languages.
basePathURL-safe path beginning with / and with no trailing slash, such as /my-toolDomain rootDeploy under a subpath.
searchBooleanfalseLocal documentation search in the navbar
TOCBooleanfalseFloating table of contents on pages with enough headings
editPagefalse or an object with baseUrlfalseShow an Edit this page link on live docs.
editPage.baseUrlAbsolute HTTP(S) URL without credentials, query, or fragmentRequired when editPage is an objectSource editor URL through the branch and, in a monorepo, the project folder

Example

ts
import { defineConfig } from '@lexibase/rdx'

export default defineConfig({
  description: 'Guides and reference for my project.',
  metadata: {
    applicationName: 'My documentation',
    metadataBase: 'https://docs.example.com',
  },
  lang: 'en',
  search: true,
  TOC: true,
  homepage: { enabled: false },
  theme: { defaultTheme: 'system' },
  navbar: {
    title: '',
    actions: {
      github: {
        visible: true,
        url: 'https://github.com/example/project',
      },
      showToggleMode: true,
    },
  },
})

Replace the GitHub action's # placeholder with your own repository URL.

lang sets the HTML language and translates built-in interface labels:

ts
lang: 'pt-BR',

Use en for English or pt-BR for Brazilian Portuguese. Portuguese locale variants, including pt, use Brazilian Portuguese labels. Other languages keep their configured HTML language and use English interface labels.

This includes search, the table of contents, copy buttons, navigation, version notices, and footer credits. Your MDX content, page titles, category names, and custom component text remain as written. Rebuild and redeploy after changing lang in production.

SEO and social previews

Use paths such as /icon.svg for files in public/. Icon, manifest, and social image fields also accept absolute HTTP(S) URLs.

OptionAccepted valueDefaultWhat it controls
metadata.applicationNameNon-empty stringRequiredSite name, browser title suffix, and branding
metadata.metadataBaseAbsolute HTTP(S) URLUnsetPublic origin used to resolve canonical, sitemap, and social URLs
metadata.sincePositive whole year up to the current yearCurrent year in the footerCopyright start year
metadata.authorsArray of { name: string, url?: string }UnsetAuthor names and optional absolute HTTP(S) profile URLs
metadata.keywordsArray of stringsUnsetMetadata keywords
metadata.iconsObjectUnsetBrowser and device icons
metadata.icons.iconURL string or array of { url: string, sizes?: string, type?: string }UnsetTab icons with optional sizes such as 96x96 or any and MIME type
metadata.icons.shortcutURL stringUnsetShortcut icon for browser compatibility
metadata.icons.appleURL stringUnsetApple home screen icon
metadata.manifestURL stringUnsetLink to an existing web app manifest

Open Graph

Set metadata.openGraph to an object to configure site-wide Open Graph previews. It is optional. The title and description defaults below apply when the object is configured. Documentation pages use their own title and description.

Field in metadata.openGraphAccepted valueDefaultWhat it controls
titleStringmetadata.applicationNameSite preview title
descriptionStringSite descriptionSite preview description
siteNameStringUnsetSite name shown by platforms that support it
localeString, such as pt_BRUnsetPreview language and region
typewebsiteUnsetOpen Graph content type
imagesArray of { url: string, width?: number, height?: number, alt?: string }UnsetPreview images with optional positive integer dimensions in pixels and alt text

Twitter and X

Set metadata.twitter to an optional object for Twitter/X card settings.

Field in metadata.twitterAccepted valueDefaultWhat it controls
cardsummary or summary_large_imagesummary_large_image with a resolved image, otherwise summaryCard layout
titleStringmetadata.applicationNameSite card title
descriptionStringSite descriptionSite card description
siteString, usually @accountUnsetAccount associated with the site
creatorString, usually @accountUnsetAccount credited as creator
imagesArray of URL stringsUnsetCard images

Metadata example

ts
metadata: {
  applicationName: 'My documentation',
  metadataBase: 'https://docs.example.com',
  authors: [{ name: 'Your team', url: 'https://example.com' }],
  keywords: ['documentation', 'my-project'],
  icons: {
    icon: [
      { url: '/icon.svg', type: 'image/svg+xml' },
      { url: '/icon.png', sizes: '96x96', type: 'image/png' },
    ],
    shortcut: '/favicon.ico',
    apple: '/apple-touch-icon.png',
  },
  manifest: '/site.webmanifest',
  openGraph: {
    type: 'website',
    images: [{
      url: '/social-preview.png',
      width: 1200,
      height: 630,
      alt: 'My documentation',
    }],
  },
  twitter: {
    card: 'summary_large_image',
    images: ['/social-preview.png'],
  },
}

This is the metadata portion of a defineConfig call, not a complete file. Place the referenced images, icons, and web app manifest in public/. For deployment under a subpath, set basePath in rdx.config.ts and keep metadata.metadataBase set to the public origin. See Deploy under a subpath.

metadataBase must be your absolute public HTTP(S) URL. RDX uses it for sitemap entries and relative social image URLs.

Documentation pages use their frontmatter title and description for browser metadata and Open Graph/Twitter link previews. When a page has no description, the site's description is used. Social images, locale, and card settings come from metadata.openGraph and metadata.twitter.

Search engine indexing

Set metadata.metadataBase to the public URL of your documentation:

ts
metadata: {
  applicationName: 'My documentation',
  metadataBase: 'https://docs.example.com',
}

RDX generates /sitemap.xml with the homepage when enabled and each indexable document. /robots.txt points search engines to this sitemap. Without a public URL, the sitemap contains no entries and robots.txt omits the sitemap address.

ContentIncluded in the sitemap and eligible for search results
Current documentation without versioningYes
Enabled homepageYes
Published editions, including previous majorsYes
Live Current/Canary with a published editionNo
Live Current/Canary without a published editionYes
Archived editionsNo
Historical redirect URLs, internal search and 404 pagesNo

The HTML directives follow the same edition policy automatically. Archiving, restoring or publishing an edition updates that policy on the next build and deployment. All documents within an edition follow its indexing policy.

Excluded documentation remains accessible. RDX allows crawlers to read its noindex directive and follow its links. These directives are not access control; search engines decide whether and when to include a page in their results.

OptionAccepted valueDefaultWhat it controls
navbarObjectRDX logo and Docs linkBranding and actions in the shared navbar
navbar.titleString''Text beside the logo
navbar.logoRoot-relative image URL from public/ or imported React component accepting classNameRDX logoCustom logo
navbar.actionsObjectOptional actions hiddenGitHub action and theme toggle
navbar.actions.showToggleModeBooleanfalseShow the theme toggle. The CLI starter sets it to true.
navbar.actions.githubObject with visible and urlUnsetGitHub link in the navbar
navbar.actions.github.visibleBooleanRequired when github is setShow the GitHub action
navbar.actions.github.urlAbsolute HTTP(S) URL or '#'Required when github is setRepository destination. '#' is a placeholder.
homepageObjectHomepage disabledConfigure the homepage.
homepage.enabledBooleanfalseShow a homepage at /. When disabled, / redirects to the docs.
homepage.componentImported React componentBuilt-in homepage when enabledRender your own components/home.tsx.
homepage.translationsBooleanfalseLoad components/home.tsx with translation catalogs. Use this in place of homepage.component.
homepage.titleNon-empty stringmetadata.applicationNameHeading on the built-in homepage
homepage.descriptionStringSite descriptionText below the built-in heading
homepage.buttonsArray of { label: string, href: string }One Docs buttonHero actions on the built-in homepage. The first is primary. Use [] to hide the buttons.

For homepage.buttons, each label is a non-empty string and each href is a root-relative path or absolute HTTP(S) URL.

Theme and code blocks

OptionAccepted valueDefaultWhat it controls
themeObjectSystem preferenceInitial theme for the shared interface
theme.defaultThemesystem, light, or darksystemTheme before the visitor saves a preference
syntaxHighlightingObjectBuilt-in languages and GitHub themesSyntax highlighting in Markdown code blocks
syntaxHighlighting.languagesObject mapping lowercase, non-reserved fence names to project-relative TextMate JSON filesNo custom grammarsHighlight a custom language.
syntaxHighlighting.themesObjectGitHub themesChoose syntax themes for each site appearance.
syntaxHighlighting.themes.lightBundled Shiki theme namegithub-lightCode colors in light mode
syntaxHighlighting.themes.darkBundled Shiki theme namegithub-darkCode colors in dark mode

Use rdx.css to customize the interface highlight color for light and dark themes.

Plugins and configuration changes

OptionAccepted valueDefaultWhat it controls
pluginsArray of RdxPlugin objects returned by plugin factories[]Active plugins, in the order they run

See Plugins for activation commands and plugin-specific configuration.

Write your documentation in docs/. Do not edit files inside .rdx/. Restart development after changing configuration, and rebuild/redeploy for production.