Skip to content

Config

Define global metadata for your documentation

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 // [!code ++]

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 Markdown
export default defineConfig({  banner: 'Head to our new [Discord](https://discord.gg/JUrRkGweXV)!', 
  title: 'Viem'
})
import { defineConfig } from 'vocs'
 

  ↓ as a React Element
export 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 object
export 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'
})

You can also define the font family for inline code & code blocks:

import { defineConfig } from 'vocs'
 
export default defineConfig({
  font: { 
    default: { 
      google: 'Inter', 
    }, 
    mono: { 
      google: 'Dancing Script', 
    }, 
  },
  title: 'Viem'
})

head

  • Type: ReactElement | { [path: string]: ReactElement } | ({ path: string }) => ReactElement)

Additional tags to include in the <head> tag of the page HTML.

Element

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'
})

Path → Element Object

You can specify a path → ReactElement object for the head with paths as keys.

import * as React from 'react'
import { defineConfig } from 'vocs'
 
export default defineConfig({
  head: { 
    '/': /* ... */, 
    '/docs': /* ... */, 
  }, 
  title: 'Viem'
})

Function

You can specify a function that returns a ReactElement. Useful if you want to have more dynamic control over rendering head tags.

import * as React from 'react'
import { defineConfig } from 'vocs'
 
export default defineConfig({
  head({ path }) { 
    if (path === '/docs') return /* ... */
    return /* ... */
  }, 
  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.

See list of plugins

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.

See list of plugins

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'
})

search

  • Type: Search

Search configuration. Accepts MiniSearch options.

import { defineConfig } from 'vocs'
 
export default defineConfig({
  search: { 
    boostDocument(documentId) { 
      return documentId === '/core' ? 2 : 1
    } 
  }, 
  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, X, and Warpcast.

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.

Read more about theming.

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()] 
  } 
})