hana-developer-cli-tool-example vitepress-config-management.instructions.md

VitePress Configuration Management Guidelines

Use this guide when creating or modifying VitePress configuration files in the docs/.vitepress/ directory.

Scope and Purpose

This guide applies to VitePress documentation site configuration:

• docs/.vitepress/config.ts - Main site configuration
• docs/.vitepress/theme/ - Custom theme files
• docs/.vitepress/components/ - Custom Vue components
• Build and deployment configurations

Critical Principles

1. Base URL: Always configure correct base URL for GitHub Pages deployment
2. Sidebar Structure: Maintain hierarchical, collapsible sidebar navigation
3. Mermaid Integration: Use withMermaid() wrapper for diagram support
4. Language Alias: Map custom syntaxes to supported highlighters
5. SEO Optimization: Include proper meta tags and descriptions
6. Clean URLs: Enable clean URLs for better user experience
7. Type Safety: Use TypeScript for configuration

Main Configuration Structure

Template: docs/.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { withMermaid } from 'vitepress-plugin-mermaid'

export default withMermaid(
  defineConfig({
    // Site Metadata
    base: '/repository-name/',
    title: 'Site Title',
    description: 'Site description for SEO',
    lang: 'en-US',
    
    // Features
    cleanUrls: true,
    ignoreDeadLinks: false,  // Set true only if needed
    appearance: 'dark',
    lastUpdated: true,
    
    // Markdown Configuration
    markdown: {
      languageAlias: {
        customLang: 'typescript'
      }
    },
    
    // HTML Head
    head: [
      ['link', { rel: 'icon', href: '/base-path/favicon.ico' }],
      ['meta', { name: 'theme-color', content: '#0092d1' }],
      ['meta', { name: 'og:type', content: 'website' }],
      ['meta', { name: 'keywords', content: 'keyword1, keyword2' }],
    ],

    // Theme Configuration
    themeConfig: {
      logo: '/logo.svg',
      siteTitle: 'Short Title',
      
      // Navigation
      nav: [
        // Navigation items
      ],
      
      // Sidebar
      sidebar: {
        // Sidebar configuration
      },
      
      // Social Links
      socialLinks: [
        { icon: 'github', link: 'https://github.com/...' }
      ],
      
      // Search
      search: {
        provider: 'local'
      },
      
      // Footer
      footer: {
        message: 'Released under the Apache License.',
        copyright: 'Copyright © 2024-present SAP'
      }
    }
  })
)