Config
Vocs uses a configuration file (vocs.config.ts
) to define global metadata for your documentation. This includes things like the site title, description, logo, sidebar, and more for your project.
Initialize Config File
The Vocs config can be defined in a vocs.config.ts
file at the root of your project.
viem/
├── docs/
├── node_modules/
├── src/
├── package.json
└── vocs.config.ts
Parameters
banner
- Type:
Banner
Configuration for the banner fixed to the top of the page.
Can be a Markdown string, a React Element, or an object with the following properties:
dismissable
: Whether or not the banner can be dismissed.backgroundColor
: The background color of the banner.content
: The content of the banner.height
: The height of the banner.textColor
: The text color of the banner.
import { defineConfig } from 'vocs'
↓ as Markdownexport default defineConfig({ banner: 'Head to our new [Discord](https://discord.gg/JUrRkGweXV)!',
title: 'Viem'
})
import { defineConfig } from 'vocs'
↓ as a React Elementexport default defineConfig({ banner: <div>Head to our new <a href="https://discord.gg/JUrRkGweXV">Discord</a></div>,
title: 'Viem'
})
import { defineConfig } from 'vocs'
↓ as an objectexport default defineConfig({ banner: {
dismissable: false,
backgroundColor: 'red',
content: 'Head to our new [Discord](https://discord.gg/JUrRkGweXV)!',
height: '28px',
textColor: 'white',
},
title: 'Viem'
})
basePath
- Type:
string
The base path the documentation will be deployed at. All assets & pages will be prefixed with this path.
For example, this is useful for deploying to GitHub Pages.
If the target URL is https://example.github.io/foo
, then the basePath
should be set to /foo
.
import { defineConfig } from 'vocs'
export default defineConfig({
basePath: '/docs',
})
baseUrl
- Type:
string
The base URL for your documentation. This is used to populate the <base>
tag in the <head>
of the page,
and is used to form the %logo
variable for dynamic OG images.
import { defineConfig } from 'vocs'
export default defineConfig({
baseUrl: 'https://vocs.dev',
})
blogDir
- Type:
string
- Default:
"./pages/blog"
Path to blog pages relative to project root. Used to extract posts from the filesystem.
import { defineConfig } from 'vocs'
export default defineConfig({
blogDir: './pages/writings',
title: 'Viem'
})
description
- Type:
string
General description for the documentation.
import { defineConfig } from 'vocs'
export default defineConfig({
description: 'Build reliable apps & libraries with lightweight, composable, and type-safe modules that interface with Ethereum.',
title: 'Viem'
})
editLink
- Type:
EditLink
Edit location for the documentation.
import { defineConfig } from 'vocs'
export default defineConfig({
editLink: {
pattern: 'https://github.com/wevm/viem/edit/main/site/pages/:path',
text: 'Edit on GitHub'
},
title: 'Viem'
})
editLink.pattern
- Type:
string | (() => string)
Edit link pattern.
import { defineConfig } from 'vocs'
export default defineConfig({
editLink: {
pattern: 'https://github.com/wevm/viem/edit/main/site/pages/:path'
},
title: 'Viem'
})
editLink.text
- Type:
string
Edit link text.
import { defineConfig } from 'vocs'
export default defineConfig({
editLink: {
pattern: 'https://github.com/wevm/viem/edit/main/site/pages/:path',
text: 'Edit on GitHub'
},
title: 'Viem'
})
font
- Type:
{ google: string }
Base font face.
import { defineConfig } from 'vocs'
export default defineConfig({
font: {
google: 'Inter'
},
title: 'Viem'
})
head
- Type:
ReactElement
Additional tags to include in the <head>
tag of the page HTML.
import * as React from 'react'
import { defineConfig } from 'vocs'
export default defineConfig({
head: (
<>
<meta property="og:type" content="website" />
<meta property="og:title" content="viem · TypeScript Interface for Ethereum" />
<meta property="og:image" content="https://viem.sh/og-image.png" />
<meta property="og:url" content="https://viem.sh" />
<meta property="og:description" content="Build reliable Ethereum apps & libraries with lightweight, composable, & type-safe modules from viem." />
</>
),
title: 'Viem'
})
iconUrl
- Type:
string | { light: string; dark: string }
Icon URL. Used as the website's favicon.
import { defineConfig } from 'vocs'
export default defineConfig({
iconUrl: '/icon.svg',
title: 'Viem'
})
You can also specify icons for light and dark mode.
import { defineConfig } from 'vocs'
export default defineConfig({
iconUrl: {
light: '/icon-light.svg',
dark: '/icon-dark.svg'
},
title: 'Viem'
})
logoUrl
- Type:
string | { light: string; dark: string }
Logo URL. Used for the sidebar and mobile top nav header image.
import { defineConfig } from 'vocs'
export default defineConfig({
logoUrl: '/logo.svg',
title: 'Viem'
})
You can also specify logos for light and dark mode.
import { defineConfig } from 'vocs'
export default defineConfig({
logoUrl: {
light: '/logo-light.svg',
dark: '/logo-dark.svg'
},
title: 'Viem'
})
markdown
- Type:
Markdown
Markdown configuration.
markdown.code
- Type:
{ theme: { light: string; dark: string } }
Used to configure the syntax highlighting theme of code blocks.
import { defineConfig } from 'vocs'
export default defineConfig({
markdown: {
code: {
themes: {
light: 'github-light',
dark: 'github-dark'
}
}
},
title: 'Viem'
})
markdown.remarkPlugins
- Type:
PluggableList
Used to configure the remark plugins used to transform Markdown.
import { defineConfig } from 'vocs'
import remarkMath from 'remark-math'
export default defineConfig({
markdown: {
remarkPlugins: [
remarkMath
]
},
title: 'Viem'
})
markdown.rehypePlugins
- Type:
PluggableList
Used to configure the rehype plugins used to transform generated HTML from Markdown.
import { defineConfig } from 'vocs'
import rehypeSlots from 'rehype-slots'
export default defineConfig({
markdown: {
rehypePlugins: [
rehypeSlots
]
},
title: 'Viem'
})
ogImageUrl
- Type:
string | { [path: string]: string }
OG Image URL. null
to disable.
import { defineConfig } from 'vocs'
export default defineConfig({
ogImageUrl: 'https://vocs.dev/api/og?logo=%logo&title=%title&description=%description',
title: 'Viem'
})
You can also specify an object for the ogImageUrl
with paths as keys.
This will render a different OG image depending on the path the user is on.
import { defineConfig } from 'vocs'
export default defineConfig({
ogImageUrl: {
'/': 'https://vocs.dev/og-image.png',
'/docs': 'https://vocs.dev/api/og?logo=%logo&title=%title&description=%description',
},
title: 'Viem'
})
rootDir
- Type:
string
- Default:
"docs"
Documentation root directory. Can be an absolute path, or a path relative from the location of the config file itself.
import { defineConfig } from 'vocs'
export default defineConfig({
rootDir: 'site',
title: 'Viem'
})
sidebar
- Type:
Sidebar
Navigation displayed on the sidebar.
import { defineConfig } from 'vocs'
export default defineConfig({
sidebar: [
{
text: 'Getting Started',
link: '/docs',
},
{
text: 'API',
collapsed: true,
items: [
{
text: 'Config',
link: '/docs/api/config',
},
],
}
],
title: 'Viem'
})
You can also specify an object for the sidebar with paths as keys and sidebar items as values.
This will render a different sidebar depending on the path the user is on.
import { defineConfig } from 'vocs'
export default defineConfig({
sidebar: {
'/guide': [{
text: 'Getting Started',
link: '/guide',
}],
'/api': [{
text: 'Config',
link: '/api/config',
}],
},
title: 'Viem'
})
socials
- Type:
Socials
Social links displayed in the top navigation.
Supports Discord, GitHub, Telegram, and X.
import { defineConfig } from 'vocs'
export default defineConfig({
socials: [
{
icon: 'github',
link: 'https://github.com/wevm/viem',
},
{
icon: 'x',
link: 'https://twitter.com/wevm_dev',
},
],
title: 'Viem'
})
sponsors
- Type:
SponsorSet
Set of sponsors to display on MDX directives and (optionally) the sidebar.
import { defineConfig } from 'vocs'
export default defineConfig({
sponsors: [
{
name: 'Collaborator',
height: 120,
items: [
[
{
name: 'Paradigm',
link: 'https://paradigm.xyz',
image:
'https://raw.githubusercontent.com/wevm/.github/main/content/sponsors/paradigm-light.svg',
},
],
],
},
{
name: 'Large Enterprise',
height: 60,
items: [
[
{
name: 'WalletConnect',
link: 'https://walletconnect.com',
image:
'https://raw.githubusercontent.com/wevm/.github/main/content/sponsors/walletconnect-light.svg',
},
{
name: 'Stripe',
link: 'https://www.stripe.com',
image:
'https://raw.githubusercontent.com/wevm/.github/main/content/sponsors/stripe-light.svg',
},
],
],
},
],
title: 'Viem'
})
theme
- Type:
Theme
Theme configuration.
import { defineConfig } from 'vocs'
export default defineConfig({
theme: {
accentColor: '#ff0000',
variables: {
color: {
background: {
light: 'white',
dark: 'black'
}
}
}
},
title: 'Viem'
})
title
- Type:
string
- Default:
"Docs"
Documentation title.
import { defineConfig } from 'vocs'
export default defineConfig({
title: 'Viem'
})
titleTemplate
- Type:
string
- Default:
"%s – Docs"
Template for the page title.
import { defineConfig } from 'vocs'
export default defineConfig({
title: 'Viem',
titleTemplate: '%s – Viem'
})
topNav
- Type:
TopNav
Navigation displayed on the top.
import { defineConfig } from 'vocs'
export default defineConfig({
title: 'Viem',
topNav: [
{ text: 'Guide & API', link: '/docs/getting-started', match: '/docs' },
{ text: 'Blog', link: '/blog' },
]
})
twoslash
- Type:
Twoslash
TwoSlash configuration.
import { defineConfig } from 'vocs'
export default defineConfig({
title: 'Viem',
twoslash: {
compilerOptions: {
strict: true,
}
}
})
vite
- Type:
Vite.UserConfig
Vite configuration. See more.
import { defineConfig } from 'vocs'
import tsconfigPaths from 'vite-tsconfig-paths'
export default defineConfig({
title: 'Viem',
vite: {
build: {
minify: 'terser'
},
plugins: [tsconfigPaths()]
}
})