Configuration

Configure renoun in your project.

This guide will help you configure renoun in your project.

renoun.json

The renoun.json file is used to globally configure components and utilities and override defaults for the entire workspace.

This file should be placed in the root of your workspace. Here is an example configuration:

renoun.json
{
  // Provide a schema for the configuration file to enable intellisense
  "$schema": "https://renoun.dev/schema.json",

  // Specify the theme to use for code highlighting
  "theme": "theme.json",

  // Specify the languages to load for code highlighting
  "languages": ["mdx", "typescript", "tsx"],

  // Specify the git information for edit links
  "git": {
    "source": "https://github.com/souporserious/renoun"
  },

  // Specify the site URL for the canonical URL
  "siteUrl": "https://renoun.dev"
}

Themes

Themes are powered by Shiki and specify how source code is highlighted in the CodeBlock and CodeInline components. You can use a bundled theme or create your own theme. The default theme is set to nord.

Bundled Themes

To use a bundled theme, you can reference a valid theme by name:

{
  "theme": "nord"
}

Custom Themes

To use a custom theme, you can reference a JSON file that defines a VS Code compatible theme:

{
  "theme": "theme.json"
}

Multiple Themes

You can also specify multiple themes to be used, the first theme will be used as the default theme:

{
  "theme": {
    "light": "vitesse-light",
    "dark": "vitesse-dark"
  }
}

This requires using the ThemeProvider component that will inject the proper CSS Variables in the head of the document:

import { ThemeProvider } from 'renoun/components'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  )
}

A data-theme attribute on the html element will be set immediately on page load before the first render based on local storage. This is why we need to suppress hydration warnings since the theme is not known until the React tree is hydrated which could have changed.

To use a specific default theme, append a data-theme attribute to the html element:

<html data-theme="dark" suppressHydrationWarning>
  ...
</html>

The useThemePicker hook can be used to build a select menu or toggle for choosing from the configured themes:

'use client'
import { useThemePicker } from 'renoun/hooks'

export function ThemePicker() {
  const [theme, setTheme] = useThemePicker()

  return (
    <select value={theme} onChange={(event) => setTheme(event.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
    </select>
  )
}

Only Loading Styles

If you are using another theming solution, you can use the ThemeStyles component directly to only load the CSS Variables for the theme:

import { ThemeStyles } from 'renoun/components'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html>
      <body>
        <ThemeStyles />
        {children}
      </body>
    </html>
  )
}

This is not required if you are using the ThemeProvider component.

Overriding Themes

To override a theme, you can provide a tuple that specifies the theme values to override:

{
  "theme": {
    "light": "vitesse-light",
    "dark": [
      "vitesse-dark",
      {
        "colors": {
          "editor.background": "#000000",
          "panel.border": "#666666"
        }
      }
    ]
  }
}

This accepts a subset of a VS Code theme to override, specifically the colors, tokenColors, and semanticTokenColors properties.

Languages

The languages property is used to define the languages that are supported by the CodeBlock and CodeInline components. This is used to determine which language to load when highlighting code.

The following languages are loaded by default:

{
  "languages": [
    "css",
    "javascript",
    "jsx",
    "typescript",
    "tsx",
    "markdown",
    "mdx",
    "shellscript",
    "json",
    "html"
  ]
}

Git Information

Git can be used to set the source, branch, and provider of your documentation site. This is used to generate the canonical URL for each page:

{
  "git": {
    "source": "https://github.com/souporserious/renoun",
    "branch": "main",
    "provider": "github"
  }
}

Site URL

The siteUrl property is used to define the URL of your documentation site. This is used to generate the canonical URL for each page:

{
  "siteUrl": "https://renoun.dev"
}
Last updated