stack/packages/mosaic/framework/skills/vitepress/references/theme-config.md

name, description

name	description
vitepress-theme-configuration	Default theme configuration for navigation, sidebar, search, social links, and footer

Theme Configuration

Configure the default theme via themeConfig in your VitePress config.

Navigation

export default {
  themeConfig: {
    // Site title in nav (overrides config.title)
    siteTitle: 'My Docs',
    siteTitle: false, // Hide title

    // Logo
    logo: '/logo.svg',
    logo: { light: '/light-logo.svg', dark: '/dark-logo.svg', alt: 'Logo' },

    // Nav links
    nav: [
      { text: 'Guide', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: 'GitHub', link: 'https://github.com/...' },
    ],
  },
};

Dropdown Menu

nav: [
  {
    text: 'Dropdown',
    items: [
      { text: 'Item A', link: '/item-a' },
      { text: 'Item B', link: '/item-b' },
    ],
  },
  // With sections
  {
    text: 'Versions',
    items: [
      {
        text: 'v2.x',
        items: [
          { text: 'v2.0', link: '/v2/' },
          { text: 'v2.1', link: '/v2.1/' },
        ],
      },
    ],
  },
];

Active Match

Control when nav item shows as active:

nav: [
  {
    text: 'Guide',
    link: '/guide/',
    activeMatch: '/guide/', // Regex pattern
  },
];

Sidebar

Simple Sidebar

sidebar: [
  {
    text: 'Guide',
    items: [
      { text: 'Introduction', link: '/guide/' },
      { text: 'Getting Started', link: '/guide/getting-started' },
    ],
  },
];

Multiple Sidebars

Different sidebar per section:

sidebar: {
  '/guide/': [
    {
      text: 'Guide',
      items: [
        { text: 'Introduction', link: '/guide/' },
        { text: 'Getting Started', link: '/guide/getting-started' }
      ]
    }
  ],
  '/api/': [
    {
      text: 'API Reference',
      items: [
        { text: 'Config', link: '/api/config' },
        { text: 'Methods', link: '/api/methods' }
      ]
    }
  ]
}

Collapsible Groups

sidebar: [
  {
    text: 'Section A',
    collapsed: false,  // Open by default, can collapse
    items: [...]
  },
  {
    text: 'Section B',
    collapsed: true,   // Collapsed by default
    items: [...]
  }
]

Base Path

Simplify links with common base:

sidebar: {
  '/guide/': {
    base: '/guide/',
    items: [
      { text: 'Intro', link: 'intro' },        // /guide/intro
      { text: 'Setup', link: 'getting-started' } // /guide/getting-started
    ]
  }
}

Search

Local Search

themeConfig: {
  search: {
    provider: 'local';
  }
}

With options:

search: {
  provider: 'local',
  options: {
    miniSearch: {
      searchOptions: {
        fuzzy: 0.2,
        prefix: true
      }
    }
  }
}

Algolia DocSearch

search: {
  provider: 'algolia',
  options: {
    appId: 'YOUR_APP_ID',
    apiKey: 'YOUR_API_KEY',
    indexName: 'YOUR_INDEX_NAME'
  }
}

Social Links

socialLinks: [
  { icon: 'github', link: 'https://github.com/...' },
  { icon: 'twitter', link: 'https://twitter.com/...' },
  { icon: 'discord', link: 'https://discord.gg/...' },
  // Custom SVG
  {
    icon: { svg: '<svg>...</svg>' },
    link: 'https://...',
    ariaLabel: 'Custom Link',
  },
];

Footer

footer: {
  message: 'Released under the MIT License.',
  copyright: 'Copyright © 2024 My Project'
}

Footer only displays on pages without sidebar.

Edit Link

editLink: {
  pattern: 'https://github.com/org/repo/edit/main/docs/:path',
  text: 'Edit this page on GitHub'
}

:path is replaced with the page's source file path.

Last Updated

Enable in site config:

export default {
  lastUpdated: true, // Get timestamp from git
};

Customize display:

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

Outline (Table of Contents)

outline: {
  level: [2, 3],      // Which heading levels to show
  label: 'On this page'
}

Or just the level:

outline: 'deep'; // Same as [2, 6]
outline: 2; // Only h2
outline: [2, 4]; // h2 through h4

Doc Footer Navigation

docFooter: {
  prev: 'Previous page',
  next: 'Next page'
}
// Or disable:
docFooter: {
  prev: false,
  next: false
}

External Link Icon

externalLinkIcon: true; // Show icon on external links

Appearance Toggle Labels

darkModeSwitchLabel: 'Appearance',
lightModeSwitchTitle: 'Switch to light theme',
darkModeSwitchTitle: 'Switch to dark theme',
sidebarMenuLabel: 'Menu',
returnToTopLabel: 'Return to top'

Key Points

• nav defines top navigation links
• sidebar can be array (single) or object (multiple sidebars)
• Use collapsed for collapsible sidebar sections
• Local search works out of the box
• editLink.pattern uses :path placeholder
• Enable lastUpdated in site config, customize in themeConfig