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:
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/components'
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"
}