You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
vitepress/docs/config/theme-configs.md

6.0 KiB

Theme Configs

Theme configs let you customize your theme. You can define theme configs by adding themeConfig key to the config file.

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

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

Here it describes the settings for the VitePress default theme. If you're using a custom theme created by others, these settings may not have any effect, or might behave differently.

  • Type: ThemeableImage

Logo file to display in nav bar, right before the site title. 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, title in nav will be disabled. Useful when you have logo that already contains the site title text.

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

nav

  • Type: NavItem

The configuration for the nav menu item. You may learn more details at 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

type NavItemWithLink = {
  text: string
  link: string
  activeMatch?: string
}

interface NavItemWithChildren {
  text?: string
  items: NavItemWithLink[]
  activeMatch?: string
}

sidebar

  • Type: Sidebar

The configuration for the sidebar menu item. You may learn more details at Theme: Sidebar.

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

interface SidebarMulti {
  [path: string]: SidebarGroup[]
}

interface SidebarGroup {
  text: string
  items: SidebarItem[]
  collapsible?: boolean
  collapsed?: boolean
}

interface SidebarItem {
  text: string
  link: string
}

outline

  • Type: number | [number, number] | 'deep' | false
  • Default: 2

The levels of header to display in the outline. You can specify a particular level by passing a number, or you can provide a level range by passing a tuple containing the bottom and upper limits. When passing 'deep' which equals [2, 6], all header levels are shown in the outline except h1. Set false to hide outline.

outlineTitle

  • Type: string
  • Default: On this page

Can be used to customize the title of the right sidebar (on the top of outline links). This is useful when writing documentation in another language.

export default {
  themeConfig: {
    outlineTitle: 'In hac pagina'
  }
}
  • Type: SocialLink[]

You may define this option to show your social account links with icons in nav.

export default {
  themeConfig: {
    socialLinks: [
      { 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: '...'
      }
    ]
  }
}
interface SocialLink {
  icon: SocialLinkIcon
  link: string
}

type SocialLinkIcon =
  | 'discord'
  | 'facebook'
  | 'github'
  | 'instagram'
  | 'linkedin'
  | 'mastodon'
  | 'slack'
  | 'twitter'
  | 'youtube'
  | { svg: string }
  • Type: Footer

Footer configuration. You can add a message or copyright text on the footer, however, it will only be displayed when the page doesn't contain a sidebar. This is 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
}
  • Type: EditLink

Edit Link lets you display a link to edit the page on Git management services such as GitHub, or GitLab. See 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
}

lastUpdatedText

  • Type: string
  • Default: Last updated

The prefix text showing right before the last updated time.

export default {
  themeConfig: {
    lastUpdatedText: 'Updated Date'
  }
}

carbonAds

  • Type: CarbonAds

A option to display Carbon Ads.

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

Learn more in 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.

export default {
  themeConfig: {
    docFooter: {
      prev: 'Pagina prior',
      next: 'Proxima pagina'
    }
  }
}
export interface DocFooter {
  prev?: string
  next?: string
}