@viteplus/versions

@viteplus/versions is a powerful VitePress plugin that enables versioned documentation with built-in localization support, seamless navigation between versions, and intelligent URL routing.

✨ Features

• Version Management: Effortlessly manage multiple documentation versions
• Localization: Full multi-language support with version-aware localization
• Smart URL Routing: Automatic path rewriting for clean, predictable URLs
• Version Switcher: Built-in component for navigating between versions
• Flexible Configuration: Customize navigation, sidebar, and URL structures per version/locale
• VitePress: support 2.0.0-alpha.12

📦 Installation

npm install @viteplus/versions
# or
yarn add @viteplus/versions
# or
pnpm add @viteplus/versions

🚀 Quick Start

1. Create a VitePress project
2. Install @viteplus/versions
3. Configure your documentation using defineVersionedConfig

// .vitepress/config.ts
import { defineVersionedConfig } from '@viteplus/versions';

export default defineVersionedConfig({
  title: 'My Project Documentation',
  description: 'Documentation with version control',
  
  // Version configuration
  versionsConfig: {
    current: 'v2.0.0',
    versionSwitcher: {
      text: 'Version',
      includeCurrentVersion: true
    }
  },
  
  // Standard VitePress configuration
  themeConfig: {
    nav: [
      { text: 'Guide', link: '/guide/' },
      { component: 'VersionSwitcher' }
    ],
    // ...
  }
});

📂 Project Structure

docs/
├── .vitepress/
│   └── config.ts
├── src/            // Current version docs
│   ├── en/         // English (default locale)
│   │   ├── index.md
│   │   └── guide/
│   └── de/         // German locale
│       ├── index.md
│       └── guide/
└── archive/       // Archived versions
    └── v1.0/
        ├── en/
        │   ├── index.md
        │   └── guide/
        └── de/
            ├── index.md
            └── guide/

🌐 Localization Support

export default defineVersionedConfig({
  // ...
  locales: {
    root: {
      lang: 'en',
      label: 'English',
      themeConfig: {
        nav: [
          { text: 'Home', link: '/' },
          { text: 'Guide', link: '/guide/' }
        ]
      }
    },
    de: {
      lang: 'de',
      label: 'Deutsch',
      themeConfig: {
        nav: [
          { text: 'Startseite', link: '/' },
          { text: 'Anleitung', link: '/guide/' }
        ]
      }
    }
  }
});

🔄 Version-Specific Navigation

export default defineVersionedConfig({
  themeConfig: {
    nav: {
      // Default navigation for all versions
      root: [
        { text: 'Home', link: '/' },
        { text: 'Guide', link: '/guide/' }
      ],
      
      // Navigation only for v1.0
      'v1.0': [
        { text: 'Home', link: '/' },
        { text: 'Legacy API', link: '/legacy-api/' }
      ]
    }
  }
});

🛠️ Custom URL Structure

export default defineVersionedConfig({
  versionsConfig: {
    // ...
    hooks: {
      rewritesHook: (source, version, locale) => {
        // Custom URL structure (version first, then locale)
        return `${version}/${locale}/${source}`;
      }
    }
  }
});

📚 Documentation

For comprehensive guides and reference, check our documentation.

• Localization
• URL Path Rewrites
• Version Switcher
• Configuration Guide

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

📄 License

This project is licensed under the MIT License.

💖 Acknowledgements

• VitePress - The amazing static site generator this plugin extends
• Vue.js - The progressive JavaScript framework
• Vite - Next generation frontend tooling
• @IMB11 - for the original vitepress-versioning-plugin

Made with ❤️ by the @viteplus team