11 KiB

Raw Blame History

Default Theme Config

The theme config lets you customize your theme. You can define it using the themeConfig option in the config file:

export default {
  lang: 'en-US',
  title: 'VitePress',
  description: 'Vite & Vue powered static site generator.',

  // Theme related configuration.
  themeConfig: {
    logo: '/logo.svg',
    nav: [...],
    sidebar: { ... }
  }
}

The options documented on this page only apply to the default theme. Different themes will expect different theme options. When using a custom theme, the theme config object will be passed to the theme directly, so the theme can define conditional behavior based on it.

i18nRouting

Type: boolean

Changing the locale to zh will change the URL from /foo (or /en/foo/) to /zh/foo. You can disable this behavior by setting themeConfig.i18nRouting to false.

logo

Type: ThemeableImage

This is the logo file to display in the navigation bar, before the site title. It accepts a path string or an object to set a different logo for light/dark mode.

export default {
  themeConfig: {
    logo: '/logo.svg'
  }
}

type ThemeableImage =
  | string
  | { src: string; alt?: string }
  | { light: string; dark: string; alt?: string }

siteTitle

Type: string | false

You can customize this item to replace the default site title (title in app config) in nav. When set to false, the navigation title will be disabled. This option is useful when you have a logo that already contains the site title text.

export default {
  themeConfig: {
    siteTitle: 'Hello World'
  }
}

nav

Type: NavItem

The configuration for navigation menu items. More details in Default Theme: Nav.

export default {
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide' },
      {
        text: 'Dropdown Menu',
        items: [
          { text: 'Item A', link: '/item-1' },
          { text: 'Item B', link: '/item-2' },
          { text: 'Item C', link: '/item-3' }
        ]
      }
    ]
  }
}

type NavItem = NavItemWithLink | NavItemWithChildren

interface NavItemWithLink {
  text: string
  link: string
  activeMatch?: string
  target?: string
  rel?: string
  noIcon?: boolean
}

interface NavItemChildren {
  text?: string
  items: NavItemWithLink[]
}

interface NavItemWithChildren {
  text?: string
  items: (NavItemChildren | NavItemWithLink)[]
  activeMatch?: string
}

sidebar

Type: Sidebar

The configuration for sidebar menu items. More details in Default Theme: Sidebar.

export default {
  themeConfig: {
    sidebar: [
      {
        text: 'Guide',
        items: [
          { text: 'Introduction', link: '/introduction' },
          { text: 'Getting Started', link: '/getting-started' },
          ...
        ]
      }
    ]
  }
}

export type Sidebar = SidebarItem[] | SidebarMulti

export interface SidebarMulti {
  [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string }
}

export type SidebarItem = {
  /**
   * The text label of the item.
   */
  text?: string

  /**
   * The link of the item.
   */
  link?: string

  /**
   * The children of the item.
   */
  items?: SidebarItem[]

  /**
   * If not specified, group is not collapsible.
   *
   * If `true`, group is collapsible and collapsed by default
   *
   * If `false`, group is collapsible but expanded by default
   */
  collapsed?: boolean

  /**
   * Base path for the children items.
   */
  base?: string

  /**
   * Customize text that appears on the footer of previous/next page.
   */
  docFooterText?: string

  rel?: string
  target?: string
}

aside

Type: boolean | 'left'
Default: true
Can be overridden per page via frontmatter

Setting this value to false prevents rendering of aside container.
Setting this value to true renders the aside to the right.
Setting this value to left renders the aside to the left.

If you want to disable it for all viewports, you should use outline: false instead.

outline

Type: Outline | Outline['level'] | false
Level can be overridden per page via frontmatter

Setting this value to false prevents rendering of outline container. Refer to this interface for more details:

interface Outline {
  /**
   * The levels of headings to be displayed in the outline.
   * Single number means only headings of that level will be displayed.
   * If a tuple is passed, the first number is the minimum level and the second number is the maximum level.
   * `'deep'` is same as `[2, 6]`, which means all headings from `<h2>` to `<h6>` will be displayed.
   *
   * @default 2
   */
  level?: number | [number, number] | 'deep'

  /**
   * The title to be displayed on the outline.
   *
   * @default 'On this page'
   */
  label?: string
}

socialLinks

Type: SocialLink[]

You can define this option to show social account links with icons in the navigation bar.

export default {
  themeConfig: {
    socialLinks: [
      // You can add any icon from simple-icons (https://simpleicons.org/):
      { icon: 'github', link: 'https://github.com/vuejs/vitepress' },
      { icon: 'twitter', link: '...' },
      // You can also add custom icons by passing SVG as string:
      {
        icon: {
          svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
        },
        link: '...',
        // You can include a custom label for accessibility too (optional but recommended):
        ariaLabel: 'cool link'
      }
    ]
  }
}

interface SocialLink {
  icon: string | { svg: string }
  link: string
  ariaLabel?: string
}

footer

Type: Footer
Can be overridden per page using frontmatter

You can add a message and/or copyright text on the footer using this option. However, it will only be displayed when the page doesn't contain a sidebar, due to design concerns.

export default {
  themeConfig: {
    footer: {
      message: 'Released under the MIT License.',
      copyright: 'Copyright © 2019-present Evan You'
    }
  }
}

export interface Footer {
  message?: string
  copyright?: string
}

editLink

Type: EditLink
Can be overridden per page via frontmatter

You can display a link to edit each documentation page at the bottom of the page. See Default Theme: Edit Link for more details.

export default {
  themeConfig: {
    editLink: {
      pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path',
      text: 'Edit this page on GitHub'
    }
  }
}

export interface EditLink {
  pattern: string
  text?: string
}

lastUpdated

Type: LastUpdatedOptions

Allows customization for the last updated text and date format.

export default {
  themeConfig: {
    lastUpdated: {
      text: 'Updated at',
      formatOptions: {
        dateStyle: 'full',
        timeStyle: 'medium'
      }
    }
  }
}

export interface LastUpdatedOptions {
  /**
   * @default 'Last updated'
   */
  text?: string

  /**
   * @default
   * { dateStyle: 'short',  timeStyle: 'short' }
   */
  formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean }
}

algolia

Type: AlgoliaSearch

An option to support searching your site with Algolia DocSearch. Learn more in Default Theme: Search

export interface AlgoliaSearchOptions extends DocSearchProps {
  locales?: Record<string, Partial<DocSearchProps>>
}

View full options here.

carbonAds

Type: CarbonAdsOptions

An option to display Carbon Ads.

export default {
  themeConfig: {
    carbonAds: {
      code: 'your-carbon-code',
      placement: 'your-carbon-placement'
    }
  }
}

export interface CarbonAdsOptions {
  code: string
  placement: string
}

Learn more in Default Theme: Carbon Ads

docFooter

Type: DocFooter

Can be used to customize text appearing above previous and next links. Helpful if not writing docs in English. Also can be used to disable prev/next links globally. If you want to selectively enable/disable previous/next links per-page, you can use frontmatter.

export default {
  themeConfig: {
    docFooter: {
      prev: 'Pagina prior',
      next: 'Proxima pagina'
    }
  }
}

export interface DocFooter {
  prev?: string | false
  next?: string | false
}

darkModeSwitchLabel

Type: string
Default: Appearance

Can be used to customize the dark mode switch label. This label is only displayed on mobile.

lightModeSwitchTitle

Type: string
Default: Switch to light theme

Can be used to customize the light mode switch title that appears on hover.

darkModeSwitchTitle

Type: string
Default: Switch to dark theme

Can be used to customize the dark mode switch title that appears on hover.

sidebarMenuLabel

Type: string
Default: Menu

Can be used to customize the sidebar menu label. This label is only displayed on mobile.

returnToTopLabel

Type: string
Default: Return to top

Can be used to customize the label of the return to top button. This label is only displayed on mobile.

langMenuLabel

Type: string
Default: Change language

Can be used to customize the aria-label of the language toggle button in navbar. This is only used if you're using i18n.

skipToContentLabel

Type: string
Default: Skip to content

Can be used to customize the label of the skip to content link. This link is shown when the user is navigating the site using a keyboard.

externalLinkIcon

Type: boolean
Default: false

Whether to show an external link icon next to external links in Markdown.

`useLayout`

Returns layout-related data. The returned object has the following type:

interface {
  isHome: ComputedRef<boolean>

  sidebar: Readonly<ShallowRef<DefaultTheme.SidebarItem[]>>
  sidebarGroups: ComputedRef<DefaultTheme.SidebarItem[]>
  hasSidebar: ComputedRef<boolean>
  isSidebarEnabled: ComputedRef<boolean>

  hasAside: ComputedRef<boolean>
  leftAside: ComputedRef<boolean>

  headers: Readonly<ShallowRef<DefaultTheme.OutlineItem[]>>
  hasLocalNav: ComputedRef<boolean>
}

Example:

<script setup>
import { useLayout } from 'vitepress/theme'

const { hasSidebar } = useLayout()
</script>

<template>
  <div v-if="hasSidebar">Only show when sidebar exists</div>
</template>

11 KiB Raw Blame History