Reference

Themes And Styling

Control the generated site's visual system with theme selection, local theme files, fonts, logos, backgrounds, links, and navigation transitions.

Theme and styling options are resolved at build time and emitted as static CSS.

Theme

By default, generated sites follow the visitor's system color scheme. lildocs uses the built-in default theme in light mode and github-dark in dark mode.

Set theme to a string to force one visual theme and syntax highlighting theme:

{
  "theme": "github-dark"
}

Use default, minimal, or any bundled Shiki theme name, such as github-light or github-dark.

Set theme.light and theme.dark to customize the system color-scheme pair:

{
  "theme": {
    "light": "github-light",
    "dark": "github-dark-dimmed"
  }
}

If the docs root contains theme.ts, lildocs loads it when theme is not set and no --theme flag is provided.

Theme resolution order is:

  1. --theme
  2. theme from config.json
  3. theme.ts in the docs root
  4. The built-in system theme pair

Local Theme Files

Create theme.ts in the docs root when you need a local theme object instead of a named built-in or Shiki theme:

export default {
  color: {
    background: "#ffffff",
    text: "#111111",
    mutedText: "#666666",
    border: "#e5e5e5",
    link: "#2563eb",
    codeBackground: "#f6f8fa",
  },
  font: {
    body: "system-ui, sans-serif",
    code: "ui-monospace, SFMono-Regular, Menlo, monospace",
  },
  background: {
    gradient: "linear-gradient(180deg, rgb(37 99 235 / 0.06), transparent 220px)",
  },
};

Local themes keep the token surface small: colors, font families, and syntax highlighting theme configuration. background.gradient and background.blendMode can be set on a local theme when the background should come from the active light or dark theme.

Local themes can also tune code foreground color, sidebar background color, and the Shiki theme used for syntax highlighting:

export default {
  color: {
    background: "#ffffff",
    text: "#111111",
    mutedText: "#666666",
    border: "#e5e5e5",
    link: "#2563eb",
    codeBackground: "#f6f8fa",
    codeForeground: "#24292e",
    sidebarBackground: "#fafafa",
  },
  font: {
    body: "system-ui, sans-serif",
    mono: "ui-monospace, SFMono-Regular, Menlo, monospace",
  },
  shiki: {
    theme: "github-light",
  },
};

Use font.code when you want to name the code font directly. Use font.mono when a local theme should provide a general monospace fallback for code.

Fonts

font configures the generated site's font families:

{
  "font": {
    "heading": "Inter",
    "body": "Source Sans 3",
    "code": "Roboto Mono"
  }
}

Font values can be Google Fonts family names or local .woff2, .woff, .ttf, or .otf file paths.

font.heading sets the font used for page titles and headings.

font.body sets the font used for normal text and interface text.

font.code sets the font used for inline code and fenced code blocks.

Favicon

favicon configures the generated site's browser icon:

{
  "favicon": "./images/favicon.svg"
}

The value can be a URL, data URL, absolute URL path, or docs-relative image file. Local image files are copied into the generated site's assets.

logo configures the generated site's header brand:

{
  "logo": {
    "image": "./images/logo.svg",
    "text": "Acme Docs",
    "font": "Onest"
  }
}

logo.image can be a URL, data URL, absolute URL path, or docs-relative image file. Local image files are copied into the generated site's assets.

logo.text sets the visible brand text. When both logo.text and logo.image are omitted, the generated header uses the nearest package.json name as the brand text.

logo.font sets the brand text font. Values can be Google Fonts family names or local .woff2, .woff, .ttf, or .otf file paths.

Background

background configures optional page background layers:

{
  "background": {
    "image": "./images/background.svg",
    "gradient": "linear-gradient(135deg, rgb(121 184 255 / 0.14), transparent 38%)",
    "blendMode": "screen"
  }
}

background.image adds a background image from a URL, CSS image function, or docs-relative file path. Local image files are copied into the generated site's assets.

{
  "background": {
    "image": "radial-gradient(circle at top, rgb(37 99 235 / 0.18), transparent 42%)"
  }
}

background.gradient adds a CSS background gradient.

background.blendMode sets background-blend-mode for the theme color and configured background layers.

No background gradient is generated by default. Add a background entry in config.json, pass the matching CLI background flags, or define background in a local theme when a page should use background layers.

link configures link presentation in generated Markdown content:

{
  "link": {
    "underline": "hover"
  }
}

link.underline controls generated content link underlines. Use always, hover, or none.

These navigation fields configure the feel of enhanced page navigation:

{
  "navigation": {
    "transition": "slide",
    "duration": 160,
    "easing": "cubic-bezier(0.16, 1, 0.3, 1)"
  }
}

navigation.transition selects the transition preset. Use fade, slide, scale, or instant.

navigation.duration sets the transition duration in milliseconds.

navigation.easing sets the CSS timing function used by transitions. Any valid CSS timing function is supported.