LitMDX

Configuration

Customize LitMDX with litmdx.config.ts

Configuration

LitMDX works without any configuration file. When you need to customize the site, create litmdx.config.ts at the project root.

Configuration file

// litmdx.config.ts
import { defineConfig } from '@litmdx/core';

export default defineConfig({
  title: 'My Docs',
  description: 'Official documentation for my project',
});

Tip

defineConfig is a no-op at runtime — it only provides TypeScript autocomplete. You can use it or skip it.

Site identity

title

Type: string — Default: 'LitMDX Docs'

Site name used in the <title> tag, the header brand, and Open Graph tags.

title: 'Acme Docs'

description

Type: string — Default: ''

Default meta description for SEO. Individual pages can override it with frontmatter.

description: 'Official documentation for the Acme SDK'

Type: string | ThemeAsset — Default: undefined

URL or path to an image that appears in the header beside the site title. Use a path relative to your public/ folder or an absolute URL.

logo: '/logo.svg'

You can also provide theme variants:

logo: {
  light: '/logo-light.svg',
  dark: '/logo-dark.svg',
}

Type: NavItem[] — Default: []

Links shown in the top navigation bar on desktop and in the mobile sidebar drawer.

nav: [
  { label: 'Guide',     to: '/basics/getting-started' },
  { label: 'Reference', to: '/reference' },
  { label: 'Blog',      href: 'https://blog.example.com' }, // opens in new tab
]

Each NavItem has two variants:

FieldTypeDescription
labelstringLink text
tostringInternal route (uses client-side navigation)
hrefstringExternal URL (opens in target="_blank")

github

Type: string — Default: undefined

URL to the GitHub repository. When set, a GitHub icon button is shown on the right side of the header.

github: 'https://github.com/you/my-project'

Content

docsDir

Type: string — Default: 'docs'

Directory containing your .mdx source files, relative to the project root.

docsDir: 'content'   // reads content/**/*.mdx

baseUrl

Type: string — Default: '/'

Base path for all routes. Set this when hosting at a sub-path (e.g. GitHub Pages project sites).

baseUrl: '/my-repo/'

Note

baseUrl is the deployment path prefix. siteUrl is the full canonical domain used for SEO artifacts such as sitemap.xml.

Head & SEO

Controls tags injected into <head> of the generated HTML.

head: {
  favicon:    '/favicon.svg',
  lang:       'en',
  author:     'Acme Corp',
  themeColor: '#6366f1',
  keywords:   ['sdk', 'api', 'docs'],
}
FieldTypeDefaultDescription
faviconstring | ThemeAsset—<link rel="icon" href="..." />
langstring'en'<html lang="..."> attribute
authorstring—<meta name="author" />
themeColorstring—<meta name="theme-color" /> (mobile browser chrome)
keywordsstring[]—<meta name="keywords" />

Theme-aware favicon example:

head: {
  favicon: {
    light: '/favicon-light.svg',
    dark: '/favicon-dark.svg',
  },
}

openGraph

Open Graph and Twitter Card metadata for link previews on social networks.

openGraph: {
  image:       'https://example.com/og.png',
  twitterCard: 'summary_large_image',
  twitterSite: '@myhandle',
  locale:      'en_US',
}
FieldTypeDefaultDescription
imagestring—og:image — absolute URL to the preview image
twitterCard'summary' | 'summary_large_image''summary'Twitter card style
twitterSitestring—twitter:site handle (e.g. '@litmdx')
localestring'en_US'og:locale

Note

og:title, og:description, and og:url are updated dynamically on each route change via the usePageMeta hook, so each page gets its own social preview automatically.

footer: {
  description: '© 2026 Acme Corp. All rights reserved.'
}
FieldTypeDescription
descriptionstringText shown on the left side of the footer

The right side always shows "Built with LitMDX".

Plugins

plugins

Pass remark and rehype plugins to extend MDX processing.

import remarkMath from 'remark-math';
import rehypeKatex from 'rehype-katex';

export default defineConfig({
  plugins: {
    remarkPlugins: [remarkMath],
    rehypePlugins: [rehypeKatex],
  },
});

Sitemap

siteUrl

Type: string — Default: undefined

Canonical base URL of your site. When set, litmdx build automatically generates a sitemap.xml in dist/ after each build.

siteUrl: 'https://docs.example.com'

See Sitemap for details.

Static Site Generation

LitMDX prerenders each known route during litmdx build, producing files like dist/index.html, dist/basics/index.html, and dist/reference/configuration/index.html.

See SSG for details and baseUrl deployment notes.

Complete example

import { defineConfig } from '@litmdx/core';

export default defineConfig({
  title: 'Acme SDK',
  description: 'Official documentation for the Acme SDK',
  logo: '/logo.svg',
  github: 'https://github.com/acme/sdk',

  nav: [
    { label: 'Guide',     to: '/basics/getting-started' },
    { label: 'Reference', to: '/reference' },
  ],

  head: {
    favicon:    '/favicon.svg',
    lang:       'en',
    author:     'Acme Corp',
    themeColor: '#0ea5e9',
    keywords:   ['acme', 'sdk', 'docs'],
  },

  openGraph: {
    image:       'https://acme.dev/og.png',
    twitterCard: 'summary_large_image',
    twitterSite: '@acmecorp',
  },

  footer: {
    description: '© 2026 Acme Corp.',
  },

  siteUrl: 'https://docs.example.com',
});