diff --git a/.github/workflows/mkdocs-dev.yml b/.github/workflows/mkdocs-dev.yml
deleted file mode 100644
index 86000997..00000000
--- a/.github/workflows/mkdocs-dev.yml
+++ /dev/null
@@ -1,34 +0,0 @@
-name: mkdocs-dev
-on:
-  push:
-    paths:
-      - 'docs/**'
-      - mkdocs.yml
-    branches:
-      - docs
-      - main
-jobs:
-  deploy:
-    name: mkdocs-dev
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout main
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          persist-credentials: true
-      - uses: actions/setup-python@v6
-        with:
-          python-version: 3.x
-      - name: Install dependencies
-        run: |
-          pip install mike
-          pip install mkdocs-material
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Configure the git user
-        run: |
-          git config user.name "Github Actions mkdocs Bot"
-          git config user.email "actions-mkdocs-bot@github.com"
-      - name: Deploy the dev documents
-        run: mike deploy --push dev
diff --git a/.github/workflows/mkdocs-latest.yml b/.github/workflows/mkdocs-latest.yml
deleted file mode 100644
index 7652de26..00000000
--- a/.github/workflows/mkdocs-latest.yml
+++ /dev/null
@@ -1,41 +0,0 @@
-name: mkdocs-latest
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: Version to be deployed
-        required: true
-  push:
-    tags:
-      - "v*"
-jobs:
-  deploy:
-    name: mkdocs-latest
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout main
-        uses: actions/checkout@v6
-        with:
-          fetch-depth: 0
-          persist-credentials: true
-      - uses: actions/setup-python@v6
-        with:
-          python-version: 3.x
-      - name: Install dependencies
-        run: |
-          pip install mike
-          pip install mkdocs-material
-        env:
-          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - name: Configure the git user
-        run: |
-          git config user.name "Github Actions mkdocs Bot"
-          git config user.email "actions-mkdocs-bot@github.com"
-      - name: Deploy the latest documents from new tag push
-        if: ${{ github.event.inputs.version == '' }}
-        run: |
-          VERSION=$(echo ${{ github.ref }} | sed -e "s#refs/tags/##g")
-          mike deploy --push --update-aliases $VERSION latest
-      - name: Deploy the latest documents from manual trigger
-        if: ${{ github.event.inputs.version != '' }}
-        run: mike deploy --push --update-aliases ${{ github.event.inputs.version }} latest
diff --git a/.github/workflows/vitepress-dev.yml b/.github/workflows/vitepress-dev.yml
new file mode 100644
index 00000000..7207815a
--- /dev/null
+++ b/.github/workflows/vitepress-dev.yml
@@ -0,0 +1,59 @@
+name: vitepress-dev
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'package.json'
+      - 'package-lock.json'
+    branches:
+      - main
+
+jobs:
+  deploy:
+    name: Deploy dev docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build VitePress
+        run: npm run docs:build
+        env:
+          VITEPRESS_BASE: /dev/
+
+      - name: Deploy to gh-pages
+        run: |
+          git config user.name "GitHub Actions Bot"
+          git config user.email "actions-bot@github.com"
+
+          # Clone gh-pages branch
+          git clone --branch gh-pages --single-branch \
+            https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git gh-pages-deploy
+
+          # Remove old dev, preserve everything else
+          rm -rf gh-pages-deploy/dev
+
+          # Copy new build
+          cp -r docs/.vitepress/dist gh-pages-deploy/dev
+
+          # Update versions.json
+          cd gh-pages-deploy
+          node ../scripts/update-versions.js dev vitepress
+
+          # Commit and push
+          git add -A
+          git diff --staged --quiet || git commit -m "Deploy dev docs"
+          git push
diff --git a/.github/workflows/vitepress-release.yml b/.github/workflows/vitepress-release.yml
new file mode 100644
index 00000000..b579775b
--- /dev/null
+++ b/.github/workflows/vitepress-release.yml
@@ -0,0 +1,72 @@
+name: vitepress-release
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: Version to deploy (e.g., v1.7.0)
+        required: true
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  deploy:
+    name: Deploy release docs
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Determine version
+        id: version
+        run: |
+          if [ -n "${{ github.event.inputs.version }}" ]; then
+            echo "version=${{ github.event.inputs.version }}" >> $GITHUB_OUTPUT
+          else
+            echo "version=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build VitePress
+        run: npm run docs:build
+        env:
+          VITEPRESS_BASE: /${{ steps.version.outputs.version }}/
+
+      - name: Deploy to gh-pages
+        run: |
+          VERSION=${{ steps.version.outputs.version }}
+          git config user.name "GitHub Actions Bot"
+          git config user.email "actions-bot@github.com"
+
+          # Clone gh-pages branch
+          git clone --branch gh-pages --single-branch \
+            https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git gh-pages-deploy
+
+          # Remove old version if exists, copy new version
+          rm -rf "gh-pages-deploy/$VERSION"
+          cp -r docs/.vitepress/dist "gh-pages-deploy/$VERSION"
+
+          # Update latest symlink (copy instead of symlink for GitHub Pages)
+          rm -rf gh-pages-deploy/latest
+          cp -r "gh-pages-deploy/$VERSION" gh-pages-deploy/latest
+
+          # Update versions.json
+          cd gh-pages-deploy
+          node ../scripts/update-versions.js "$VERSION" vitepress latest
+
+          # Commit and push
+          git add -A
+          git commit -m "Deploy $VERSION docs"
+          git push
diff --git a/.gitignore b/.gitignore
index a8e84167..ef40f07f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,3 +43,11 @@ dist/
 .env
 .envrc
 .dev_config
+
+# Node.js
+node_modules/
+package-lock.json
+
+# VitePress build output
+docs/.vitepress/dist/
+docs/.vitepress/cache/
diff --git a/.gitpod.yml b/.gitpod.yml
index bc4c0b9a..360e7fd5 100644
--- a/.gitpod.yml
+++ b/.gitpod.yml
@@ -1,7 +1,7 @@
 tasks:
   - name: Setup
     init: |
-      pip install pre-commit mkdocs mkdocs-material && pre-commit install
+      pip install pre-commit && pre-commit install && npm install
     command: |
       make install generate
 ports:
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7b7f4d80..b6c79c1b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,8 +20,8 @@ Setting up a test environment involves the following steps:
 * Install [pre-commit](https://pre-commit.com/)
 * Run `pre-commit install`
 * For working on the documentation:
-    * Install [mkdocs](https://www.mkdocs.org/)
-    * Install [mkdocs-material](https://github.com/squidfunk/mkdocs-material)
+    * Install [Node.js](https://nodejs.org/) (v18+)
+    * Run `npm install` in the project root
 
 After this, you'll be able to test any change. Alternatively, you can open the project via Gitpod: 
 
@@ -45,6 +45,8 @@ make test # Run all tests
 make lint # Run the linter to detect any issues
 make mocks # (Re-)generate the mock files
 pre-commit run --all-files # Run all pre-commit hooks manually
+npm run docs:dev # Start local documentation server
+npm run docs:build # Build documentation for production
 ```
 
 ## Features and bugs
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
new file mode 100644
index 00000000..afcf8d8c
--- /dev/null
+++ b/docs/.vitepress/config.ts
@@ -0,0 +1,92 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+  title: "SnipKit Documentation",
+  description:
+    "SnipKit helps you to execute scripts saved in your favorite snippets manager without even leaving the terminal.",
+
+  base: process.env.VITEPRESS_BASE || "/",
+
+  head: [["link", { rel: "icon", href: "/images/logo.png" }]],
+
+  themeConfig: {
+    logo: "/images/logo.png",
+
+    nav: [
+      { text: "Home", link: "/" },
+      { text: "Getting Started", link: "/getting-started/overview" },
+      { text: "Configuration", link: "/configuration/overview" },
+      { text: "Managers", link: "/managers/overview" },
+      { text: "Assistant", link: "/assistant/" },
+    ],
+
+    sidebar: {
+      "/getting-started/": [
+        {
+          text: "Getting Started",
+          items: [
+            { text: "Overview", link: "/getting-started/overview" },
+            { text: "Parameters", link: "/getting-started/parameters" },
+            { text: "Power Setup", link: "/getting-started/power-setup" },
+            { text: "Fzf", link: "/getting-started/fzf" },
+          ],
+        },
+      ],
+      "/configuration/": [
+        {
+          text: "Configuration",
+          items: [
+            { text: "Overview", link: "/configuration/overview" },
+            { text: "Themes", link: "/configuration/themes" },
+          ],
+        },
+      ],
+      "/managers/": [
+        {
+          text: "Managers",
+          items: [
+            { text: "Overview", link: "/managers/overview" },
+            { text: "File System Library", link: "/managers/fslibrary" },
+            { text: "GitHub Gist", link: "/managers/githubgist" },
+            { text: "SnippetsLab", link: "/managers/snippetslab" },
+            { text: "Snip", link: "/managers/pictarinesnip" },
+            { text: "Pet", link: "/managers/pet" },
+          ],
+        },
+      ],
+      "/assistant/": [
+        {
+          text: "Assistant",
+          items: [
+            { text: "Overview", link: "/assistant/" },
+            { text: "OpenAI", link: "/assistant/openai" },
+            { text: "Anthropic", link: "/assistant/anthropic" },
+            { text: "Gemini", link: "/assistant/gemini" },
+            { text: "Ollama", link: "/assistant/ollama" },
+            { text: "OpenAI-Compatible", link: "/assistant/openai-compatible" },
+          ],
+        },
+      ],
+    },
+
+    socialLinks: [
+      { icon: "github", link: "https://github.com/lemoony/snipkit" },
+    ],
+
+    footer: {
+      message: "Released under the Apache License 2.0.",
+      copyright: "Copyright © 2026 lemoony",
+    },
+
+    search: {
+      provider: "local",
+    },
+  },
+
+  markdown: {
+    theme: {
+      light: "catppuccin-latte",
+      dark: "catppuccin-mocha",
+    },
+  },
+});
diff --git a/docs/.vitepress/theme/Layout.vue b/docs/.vitepress/theme/Layout.vue
new file mode 100644
index 00000000..ab1cecbd
--- /dev/null
+++ b/docs/.vitepress/theme/Layout.vue
@@ -0,0 +1,14 @@
+<script setup lang="ts">
+import DefaultTheme from 'vitepress/theme'
+import VersionSwitcher from './components/VersionSwitcher.vue'
+
+const { Layout } = DefaultTheme
+</script>
+
+<template>
+  <Layout>
+    <template #nav-bar-content-after>
+      <VersionSwitcher />
+    </template>
+  </Layout>
+</template>
diff --git a/docs/.vitepress/theme/components/VersionSwitcher.vue b/docs/.vitepress/theme/components/VersionSwitcher.vue
new file mode 100644
index 00000000..7fcd749e
--- /dev/null
+++ b/docs/.vitepress/theme/components/VersionSwitcher.vue
@@ -0,0 +1,209 @@
+<script setup lang="ts">
+import { ref, onMounted, computed } from 'vue'
+
+interface Version {
+  version: string
+  title: string
+  aliases: string[]
+  type?: string
+}
+
+const versions = ref<Version[]>([])
+const currentVersion = ref('dev')
+const siteRoot = ref('/')
+const isOpen = ref(false)
+
+const sortedVersions = computed(() => {
+  return versions.value.slice().sort((a, b) => {
+    // dev always first
+    if (a.version === 'dev') return -1
+    if (b.version === 'dev') return 1
+    // latest alias second
+    if (a.aliases?.includes('latest')) return -1
+    if (b.aliases?.includes('latest')) return 1
+    // then by version number descending
+    return b.version.localeCompare(a.version, undefined, { numeric: true })
+  })
+})
+
+onMounted(async () => {
+  // Detect site root and current version from URL
+  // URL patterns:
+  // - GitHub Pages: /snipkit/dev/page.html -> siteRoot=/snipkit, version=dev
+  // - GitHub Pages: /snipkit/v1.6.1/page.html -> siteRoot=/snipkit, version=v1.6.1
+  // - Local dev: /page.html -> siteRoot='', version=dev (default)
+
+  const pathname = window.location.pathname
+
+  // Pattern: optional repo name, then version (dev, latest, or vX.X.X)
+  // e.g., /snipkit/dev/page or /snipkit/v1.6.1/page or /dev/page
+  const versionPattern = /^(\/snipkit)?\/(v[\d.]+|dev|latest)(\/|$)/
+  const match = pathname.match(versionPattern)
+
+  if (match) {
+    // Has a version in the path
+    siteRoot.value = match[1] || ''  // e.g., '/snipkit' or ''
+    currentVersion.value = match[2]   // e.g., 'dev', 'v1.6.1', 'latest'
+  } else {
+    // No version in path - local dev mode
+    siteRoot.value = ''
+    currentVersion.value = 'dev'
+  }
+
+  // Fetch versions.json from site root (or current origin for local dev)
+  const versionsUrl = siteRoot.value ? `${siteRoot.value}/versions.json` : '/versions.json'
+  try {
+    const response = await fetch(versionsUrl)
+    if (response.ok) {
+      versions.value = await response.json()
+    }
+  } catch (e) {
+    console.error('Failed to load versions from', versionsUrl, e)
+  }
+})
+
+function getVersionLabel(v: Version): string {
+  if (v.aliases?.includes('latest')) {
+    return `${v.title} (latest)`
+  }
+  return v.title
+}
+
+function switchVersion(version: Version) {
+  // Get the current page path without version prefix
+  const pathname = window.location.pathname
+  const pathAfterVersion = pathname.replace(/^(\/[^/]+)?\/(v[\d.]+|dev|latest)/, '')
+
+  // Build new URL
+  const newPath = `${siteRoot.value}/${version.version}${pathAfterVersion || '/'}`
+  window.location.href = newPath
+}
+
+function handleClickOutside(event: MouseEvent) {
+  const target = event.target as HTMLElement
+  if (!target.closest('.version-switcher')) {
+    isOpen.value = false
+  }
+}
+
+onMounted(() => {
+  document.addEventListener('click', handleClickOutside)
+})
+</script>
+
+<template>
+  <div class="version-switcher" v-if="versions.length > 0">
+    <button @click.stop="isOpen = !isOpen" class="version-button">
+      <span class="version-text">{{ currentVersion }}</span>
+      <svg
+        class="arrow"
+        :class="{ open: isOpen }"
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="currentColor"
+      >
+        <path d="M7 10l5 5 5-5z"/>
+      </svg>
+    </button>
+    <Transition name="dropdown">
+      <ul v-if="isOpen" class="version-dropdown">
+        <li v-for="v in sortedVersions" :key="v.version">
+          <a
+            @click.prevent="switchVersion(v)"
+            :class="{ current: v.version === currentVersion }"
+          >
+            {{ getVersionLabel(v) }}
+          </a>
+        </li>
+      </ul>
+    </Transition>
+  </div>
+</template>
+
+<style scoped>
+.version-switcher {
+  position: relative;
+  margin-left: 16px;
+}
+
+.version-button {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  padding: 4px 12px;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  background: var(--vp-c-bg-soft);
+  color: var(--vp-c-text-1);
+  font-size: 13px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+}
+
+.version-button:hover {
+  border-color: var(--vp-c-brand-1);
+  background: var(--vp-c-bg-mute);
+}
+
+.version-text {
+  min-width: 48px;
+  text-align: center;
+}
+
+.arrow {
+  transition: transform 0.2s ease;
+}
+
+.arrow.open {
+  transform: rotate(180deg);
+}
+
+.version-dropdown {
+  position: absolute;
+  top: calc(100% + 8px);
+  right: 0;
+  min-width: 140px;
+  max-height: 320px;
+  overflow-y: auto;
+  padding: 8px 0;
+  background: var(--vp-c-bg-soft);
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 8px;
+  box-shadow: 0 4px 16px rgba(0, 0, 0, 0.1);
+  list-style: none;
+  z-index: 100;
+}
+
+.version-dropdown li a {
+  display: block;
+  padding: 8px 16px;
+  color: var(--vp-c-text-2);
+  font-size: 13px;
+  cursor: pointer;
+  transition: all 0.15s ease;
+}
+
+.version-dropdown li a:hover {
+  background: var(--vp-c-bg-mute);
+  color: var(--vp-c-text-1);
+}
+
+.version-dropdown li a.current {
+  color: var(--vp-c-brand-1);
+  font-weight: 600;
+}
+
+/* Dropdown animation */
+.dropdown-enter-active,
+.dropdown-leave-active {
+  transition: all 0.2s ease;
+}
+
+.dropdown-enter-from,
+.dropdown-leave-to {
+  opacity: 0;
+  transform: translateY(-8px);
+}
+</style>
diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
new file mode 100644
index 00000000..4904b4ed
--- /dev/null
+++ b/docs/.vitepress/theme/index.ts
@@ -0,0 +1,9 @@
+import DefaultTheme from 'vitepress/theme'
+import '@catppuccin/vitepress/theme/mocha/mauve.css'
+import Layout from './Layout.vue'
+import type { Theme } from 'vitepress'
+
+export default {
+  extends: DefaultTheme,
+  Layout
+} satisfies Theme
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 00000000..65f5f637
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,78 @@
+# SnipKit Documentation
+
+This folder contains the VitePress-based documentation for SnipKit.
+
+## Local Development
+
+```bash
+# Install dependencies (from repo root)
+npm install
+
+# Start dev server
+npm run docs:dev
+
+# Build for production
+npm run docs:build
+
+# Preview production build
+npm run docs:preview
+```
+
+## Structure
+
+```
+docs/
+├── .vitepress/
+│   ├── config.ts              # VitePress configuration
+│   └── theme/
+│       ├── index.ts           # Theme setup (Catppuccin)
+│       ├── Layout.vue         # Custom layout with version switcher
+│       └── components/
+│           └── VersionSwitcher.vue
+├── public/
+│   ├── images/                # Static assets
+│   └── versions.json          # Mock versions for local dev
+├── getting-started/
+├── configuration/
+├── managers/
+├── assistant/
+└── index.md                   # Home page
+```
+
+## Versioning
+
+Documentation uses directory-based versioning similar to mike:
+
+- Each version is deployed to its own directory on gh-pages (`/dev/`, `/v1.6.1/`, etc.)
+- A `versions.json` file at the gh-pages root lists all available versions
+- The version switcher reads this file and allows navigation between versions
+- Old mkdocs versions remain accessible alongside new VitePress versions
+
+### versions.json Format
+
+```json
+[
+  {"version": "dev", "title": "dev", "aliases": []},
+  {"version": "v1.7.0", "title": "v1.7.0", "aliases": ["latest"]},
+  {"version": "v1.6.1", "title": "v1.6.1", "aliases": []}
+]
+```
+
+## Deployment
+
+Two GitHub Actions workflows handle deployment:
+
+### Dev Deployment (`.github/workflows/vitepress-dev.yml`)
+- **Trigger**: Push to `main` branch (when `docs/**` or `package.json` changes)
+- **Deploys to**: `gh-pages/dev/`
+
+### Release Deployment (`.github/workflows/vitepress-release.yml`)
+- **Trigger**: Push tag `v*` or manual workflow dispatch
+- **Deploys to**: `gh-pages/$VERSION/` and updates `gh-pages/latest/`
+
+## Theme
+
+Uses [Catppuccin](https://github.com/catppuccin/vitepress) theme:
+- **Dark mode**: Mocha flavor with Mauve accent
+- **Light mode**: Latte flavor
+
diff --git a/docs/assistant/anthropic.md b/docs/assistant/anthropic.md
index 716a7c04..ce94df40 100644
--- a/docs/assistant/anthropic.md
+++ b/docs/assistant/anthropic.md
@@ -4,7 +4,7 @@ Use Anthropic's Claude models as your SnipKit assistant.
 
 ## Configuration
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
@@ -22,7 +22,7 @@ config:
 
 You need to provide the API key for the Anthropic API via the environment variable specified in `apiKeyEnv`.
 
-```sh title="Set Anthropic API Key"
+```sh [Set Anthropic API Key]
 export SNIPKIT_ANTHROPIC_API_KEY="your-api-key-here"
 ```
 
diff --git a/docs/assistant/gemini.md b/docs/assistant/gemini.md
index 1afa5eb6..c97a374a 100644
--- a/docs/assistant/gemini.md
+++ b/docs/assistant/gemini.md
@@ -4,7 +4,7 @@ Use Google's Gemini models as your SnipKit assistant.
 
 ## Configuration
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
@@ -24,7 +24,7 @@ config:
 
 You need to provide the API key for the Gemini API via the environment variable specified in `apiKeyEnv`.
 
-```sh title="Set Gemini API Key"
+```sh [Set Gemini API Key]
 export SNIPKIT_GEMINI_API_KEY="your-api-key-here"
 ```
 
diff --git a/docs/assistant/index.md b/docs/assistant/index.md
index 237a708d..b38ca866 100644
--- a/docs/assistant/index.md
+++ b/docs/assistant/index.md
@@ -2,26 +2,27 @@
 
 The SnipKit Assistant helps you create SnipKit snippets using AI through an interactive chat-style interface. Generate scripts from natural language prompts, execute them with real-time output preview, and refine with follow-up prompts—all in a unified workflow.
 
-!!! tip
-    Alternatively, you may try using [SnipKit GPT](https://chatgpt.com/g/g-A2y9cPWE7-snipkit-assistant) to generate scripts compatible with SnipKit.
+::: tip
+Alternatively, you may try using [SnipKit GPT](https://chatgpt.com/g/g-A2y9cPWE7-snipkit-assistant) to generate scripts compatible with SnipKit.
+:::
 
-![Assistant Demo](../images/assistant/assistant.gif)
+![Assistant Demo](/images/assistant/assistant.gif)
 
 ## Supported AI Providers
 
-- [OpenAI](openai.md)
-- [Anthropic](anthropic.md)
-- [Google Gemini](gemini.md)
-- [Ollama](ollama.md) (local models)
-- [OpenAI-Compatible](openai-compatible.md) (Together.ai, Groq, Azure OpenAI, etc.)
+- [OpenAI](openai)
+- [Anthropic](anthropic)
+- [Google Gemini](gemini)
+- [Ollama](ollama) (local models)
+- [OpenAI-Compatible](openai-compatible) (Together.ai, Groq, Azure OpenAI, etc.)
 
 ## Generate Scripts
 
-```sh title="Generate a Script"
+```sh [Generate a Script]
 snipkit assistant generate
 ```
 
-```sh title="Root-Level Command for Convenience"
+```sh [Root-Level Command for Convenience]
 snipkit ai
 ```
 
@@ -50,18 +51,19 @@ If the script didn't work as expected or you want to refine it, select **Revise*
 - Generated scripts
 - Execution output and results
 
-![Assistant Wizard](../images/assistant//assistant-zip.gif)
+![Assistant Wizard](/images/assistant/assistant-zip.gif)
 
 When you provide a follow-up prompt, SnipKit automatically includes the context from previous interactions, so you can simply describe what needs to change.
 
-!!! tip
-    If the script failed due to errors visible in the output, try revising with an empty prompt—the AI will use the error output to fix the issue automatically.
+::: tip
+If the script failed due to errors visible in the output, try revising with an empty prompt—the AI will use the error output to fix the issue automatically.
+:::
 
 ## Save Generated Snippets
 
 SnipKit supports saving generated snippets to your [File System Library][fslibrary].
 
-![Assistant Wizard](../images/assistant/assistant-save.gif)
+![Assistant Wizard](/images/assistant/assistant-save.gif)
 
 After executing a script, select **Save & Exit** (`S`) from the action bar. A modal dialog lets you specify:
 
@@ -70,33 +72,34 @@ After executing a script, select **Save & Exit** (`S`) from the action bar. A mo
 
 If you set `saveMode: FS_LIBRARY`, the save option will be available in the post-execution action bar.
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
     saveMode: FS_LIBRARY
 ```
 
-!!! note
-    The [File System Library manager][fslibrary] must be enabled.
+::: tip
+The [File System Library manager][fslibrary] must be enabled.
+:::
 
-[fslibrary]: ../managers/fslibrary.md
+[fslibrary]: ../managers/fslibrary
 
 ## Configuration
 
 This command lets you enable the assistant by editing your SnipKit configuration file:
 
-```sh title="Enable or Switch to a Different AI Provider"
+```sh [Enable or Switch to a Different AI Provider]
 snipkit assistant choose
 ```
 
-![Assistant Choose](../images/assistant/assistant-choose.gif)
+![Assistant Choose](/images/assistant/assistant-choose.gif)
 
 You will need to provide an API key for the corresponding AI provider via an environment variable.
 
-[configuration]: ../configuration/overview.md
+[configuration]: ../configuration/overview
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
@@ -121,5 +124,6 @@ config:
         serverUrl: http://localhost:11434
 ```
 
-!!! note
-    The first provider with `enabled: true` will be used. If all providers are set to `enabled: false`, the assistant will not function.
+::: tip
+The first provider with `enabled: true` will be used. If all providers are set to `enabled: false`, the assistant will not function.
+:::
diff --git a/docs/assistant/ollama.md b/docs/assistant/ollama.md
index 8a1fa250..5492f704 100644
--- a/docs/assistant/ollama.md
+++ b/docs/assistant/ollama.md
@@ -10,7 +10,7 @@ Use local LLMs via Ollama as your SnipKit assistant. This allows you to run AI m
 
 ## Configuration
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
@@ -24,8 +24,9 @@ config:
         serverUrl: http://localhost:11434
 ```
 
-!!! note
-    No API key is required since Ollama runs locally.
+::: tip
+No API key is required since Ollama runs locally.
+:::
 
 Pull a model before using it:
 
diff --git a/docs/assistant/openai-compatible.md b/docs/assistant/openai-compatible.md
index bb20fb24..4850a820 100644
--- a/docs/assistant/openai-compatible.md
+++ b/docs/assistant/openai-compatible.md
@@ -4,7 +4,7 @@ Use any service that implements the OpenAI API format as your SnipKit assistant.
 
 ## Configuration
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
diff --git a/docs/assistant/openai.md b/docs/assistant/openai.md
index b4646a89..5377acac 100644
--- a/docs/assistant/openai.md
+++ b/docs/assistant/openai.md
@@ -4,7 +4,7 @@ Use OpenAI's GPT models as your SnipKit assistant.
 
 ## Configuration
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.3.0
 config:
   assistant:
@@ -24,7 +24,7 @@ config:
 
 You need to provide the API key for the OpenAI API via the environment variable specified in `apiKeyEnv`.
 
-```sh title="Set OpenAI API Key"
+```sh [Set OpenAI API Key]
 export SNIPKIT_OPENAI_API_KEY="your-api-key-here"
 ```
 
diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md
index c054c469..01732b2b 100644
--- a/docs/configuration/overview.md
+++ b/docs/configuration/overview.md
@@ -18,9 +18,10 @@ want to put the following into your `~/.zshrc` file:
 export SNIPKIT_HOME=/Users/<user>/.snipkit
 ```
 
-!!! warning "Use absolute paths for `SNIPKIT_HOME`"
-    Please make sure to use an absolute path for `SNIPKIT_HOME` and do not use the tilde (~) character to point to your 
-    home directory. Otherwise, SnipKit will not be able to find your configuration file.
+::: warning Use absolute paths for `SNIPKIT_HOME`
+Please make sure to use an absolute path for `SNIPKIT_HOME` and do not use the tilde (~) character to point to your 
+home directory. Otherwise, SnipKit will not be able to find your configuration file.
+:::
 
 ## Initialization
 
@@ -32,8 +33,8 @@ snipkit config init
 
 This command creates a config file in the SnipKit home directory. The initial config file looks similar to this:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   style:
     # The theme defines the terminal colors used by Snipkit.
@@ -73,8 +74,8 @@ When typing `snipkit config edit` the configuration file will be opened in an ed
 The default editor is defined by the `$VISUAL` or `$EDITOR` environment variables. This behavior can be overwritten by
 setting the `editor` field in the configuration file to a non-empty string, e.g.:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   editor: "code"
 ```
@@ -86,10 +87,10 @@ If no value is provided at all, SnipKit will try to use `vim`.
 Most of the time, you want to call the same subcommand, e.g. `print` or `exec`. You can configure `snipkit` so that this
 command gets executed by default:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
-  defaultRootCommand: "exec"
+  defaultRootCommand: "exec
 ```
 
 This way, calling `snipkit` will yield the same result as `snipkit exec`. If you want to call the `print` command instead,
@@ -100,8 +101,8 @@ you can still call `snipkit print`.
 Enable fuzzy searching for snippet titles. This leads to potentially more snippets matching the search criteria. Snipkit
 will try to rank them according to similarity. Disable fuzzy search for performance reasons or if you just don't like it.
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   fuzzySearch: true
 ```
@@ -112,22 +113,24 @@ On linux machines, the keyring for storing secrets may not be accessible for Sni
 
 The secrets will be stored in `<snipkit_home>/.secrets/`.
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   secretStorage: KEYRING 
 ```
 
 Allowed Values: `KEYRING` | `PLAIN_FILES`
 
-!!! info
-    As of now, only the access token for the [GitHub Gist manager](githubgist) is stored as a secret.
+::: info
+As of now, only the access token for the [GitHub Gist manager][githubgist] is stored as a secret.
+:::
 
-!!! danger
-    Don't change this config to `PLAIN_FILES` unless you experience any problems with the keyring. This config option is only a temporary workaround for [go-keyring#116](https://github.com/zalando/go-keyring/issues/116) (see also [SnipKit Issue #268](https://github.com/lemoony/snipkit/issues/268)) and will be removed as soon as the related issue is fixed.
+::: danger
+Don't change this config to `PLAIN_FILES` unless you experience any problems with the keyring. This config option is only a temporary workaround for [go-keyring#116](https://github.com/zalando/go-keyring/issues/116) (see also [SnipKit Issue #268](https://github.com/lemoony/snipkit/issues/268)) and will be removed as soon as the related issue is fixed.
+:::
 
 
-[githubgist]: ../managers/githubgist.md
+[githubgist]: ../managers/githubgist
 
 
 ### Style
@@ -136,8 +139,8 @@ Allowed Values: `KEYRING` | `PLAIN_FILES`
 
 SnipKit supports multiple themes out of the box and also allows you to define your own themes:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   style:
     theme: "default"
@@ -153,8 +156,8 @@ For a list of supported default themes, have a look at the [Themes][themes] page
 By default, a help for the key mapping is displayed at the bottom of the screen. To save same screen space, this can be 
 disabled:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   style:
     hideKeyMap: true
@@ -167,8 +170,8 @@ config:
 The shell for script executions is defined by the `$SHELL` environment variable. This behavior can be overwritten by setting
 the `shell` option to a non-empty string, e.g.:
 
-```yaml title="config.yaml"
-version: 1.2.0 
+```yaml [config.yaml]
+version: 1.3.0 
 config:
   script:
     shell: "/bin/zsh"
@@ -180,8 +183,8 @@ If neither `$SHELL` nor the config option `shell` is defined, SnipKit will try t
 
 How values are injected into your snippet for the defined parameters is defined by the `parameterMode` option:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   script:
     parameterMode: SET
@@ -189,7 +192,7 @@ config:
 
 The default value is `SET`, defining that values should be set as variables. This means that the following script
 
-```sh title="Raw snippet before execution"
+```sh [Raw snippet before execution]
 # ${VAR} Description: What to print
 echo ${VAR}
 ```
@@ -205,7 +208,7 @@ echo ${VAR}
 Alternatively, all occurrences of a parameter can be replaced with the actual value when 
 specifying `REPLACE` for `parameterMode`:
 
-```sh title="Example for parameterMode = REPLACE"
+```sh [Example for parameterMode = REPLACE]
 echo "Hello world"
 ```
 
@@ -213,8 +216,8 @@ echo "Hello world"
 
 SnipKit will remove all parameter comments from a snippet when specifying `removeComments`:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   script:
     removeComments: true
@@ -222,7 +225,7 @@ config:
 
 This means that the following script
 
-```sh title="Raw snippet before execution"
+```sh [Raw snippet before execution]
 # ${VAR} Description: What to print
 echo ${VAR}
 ```
@@ -233,52 +236,55 @@ will be formatted in the following way:
 echo ${VAR}
 ```
 
-!!! info
-    Comments will always be removed if `parameterMode` is set to `REPLACE`.
+::: info
+Comments will always be removed if `parameterMode` is set to `REPLACE`.
+:::
 
 #### Confirm Commands
 
 If you always want to explicitly confirm the command before execution, specify the `execConfirm` option as follows:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   script:
     execConfirm: true
 ```
 
-!!! tip "Flag --confirm"
-    The same functionality can be achieved by means of the `--confirm` flag:
-    ```bash
-    snipkit exec --confirm
-    ```
-    Use the flag instead of the config option if you only want to explicitly confirm the command in some cases.
+::: tip Flag --confirm
+The same functionality can be achieved by means of the `--confirm` flag:
+```bash
+snipkit exec --confirm
+```
+Use the flag instead of the config option if you only want to explicitly confirm the command in some cases.
+:::
 
 
 #### Print Commands
 
 SnipKit will print the command to be executed on stdout if specified by the `execPrint` commands:
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   script:
     execPrint: true
 ```
 
-!!! tip "Flag -p or --print"
-    The same functionality can be achieved by means of the `-p` or `--print` flag:
-    ```bash 
-    snipkit exec --print
-    ```
-    Use the flag instead of the config option if you only want to print the command every now and then.
+::: tip Flag -p or --print
+The same functionality can be achieved by means of the `-p` or `--print` flag:
+```bash 
+snipkit exec --print
+```
+Use the flag instead of the config option if you only want to print the command every now and then.
+:::
 
 ### Assistant
 
 Have a look at the [Assistant][assistant] page on how to configure the assistant.
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   assistant: {}
 ```
@@ -288,8 +294,8 @@ config:
 Have a look at the [Managers][managers] page on how to configure managers.
 
 
-```yaml title="config.yaml"
-version: 1.2.0
+```yaml [config.yaml]
+version: 1.3.0
 config:
   managers: {}
 ```
@@ -306,6 +312,6 @@ snipkit config clean
 The cleanup method is a way to remove all SnipKit artifacts from your hard drive. It only deletes contents of the SnipKit
 home directory. If this directory is empty at the end of the cleanup process, it will be deleted as well.
 
-[managers]: ../managers/overview.md
-[assistant]: ../assistant/index.md
-[themes]: themes.md
+[managers]: ../managers/overview
+[assistant]: ../assistant/index
+[themes]: themes
diff --git a/docs/configuration/themes.md b/docs/configuration/themes.md
index d960d29a..97fb79e4 100644
--- a/docs/configuration/themes.md
+++ b/docs/configuration/themes.md
@@ -4,7 +4,7 @@ SnipKit supports built-in themes as well as the possibility to define your own c
 
 In order to pick a different theme, edit the [configuration][configuration]:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 version: 1.0.0
 config:
   style:
@@ -13,10 +13,11 @@ config:
 
 Themes may have different variants for light & dark backgrounds, depending on your terminal.
 
-!!! warning "Enforce light or dark theme"
-    Sometimes SnipKit is not able to detect if you're using a light or dark background correctly. You can force a specific
-    theme variant by explicitly defining the `.light` or `.dark` suffix, e.g., `default.light` or `default.dark` as
-    theme name in your `config.yaml`.
+::: warning Enforce light or dark theme
+Sometimes SnipKit is not able to detect if you're using a light or dark background correctly. You can force a specific
+theme variant by explicitly defining the `.light` or `.dark` suffix, e.g., `default.light` or `default.dark` as
+theme name in your `config.yaml`.
+:::
 
 ## Built-in themes
 
@@ -26,18 +27,18 @@ As of now, the following themes are supported:
 
 #### Dark
 
-![Default Dark Lookup](../images/themes/default-dark-lookup.png){ align=left, width=49% }
-![Default Dark Parameters](../images/themes/default-dark-form.png){ align=right, width=49% }
+![Default Dark Lookup](/images/themes/default-dark-lookup.png)
+![Default Dark Parameters](/images/themes/default-dark-form.png)
 
 #### Light
 
-![Default Light Lookup](../images/themes/default-light-lookup.png){ align=left, width=49% }
-![Default Light Parameters](../images/themes/default-light-form.png){ align=right, width=49% }
+![Default Light Lookup](/images/themes/default-light-lookup.png)
+![Default Light Parameters](/images/themes/default-light-form.png)
 
 ### Simple Theme
 
-![Simple Lookup](../images/themes/simple-lookup.png){ align=left, width=49% }
-![Simple Parameters](../images/themes/simple-form.png){ align=right, width=49% }
+![Simple Lookup](/images/themes/simple-lookup.png)
+![Simple Parameters](/images/themes/simple-form.png)
 
 ## Custom themes
 
@@ -46,7 +47,7 @@ Custom themes should be placed in the directory `<snipkit_home>/themes/`,
 
 A theme called `custom-theme` should be put into a file named `custom-theme.yaml`. The contents are as follows:
 
-```yaml title="custom-theme.yaml"
+```yaml [custom-theme.yaml]
 version: 1.0.0
 variables:
   white: "#FFFFFF"
@@ -78,13 +79,15 @@ theme:
   snippetContrastColor: ${black}
 ```
 
-!!! tip "Example themes"
-    You can have a look at the [built-in themes](https://github.com/lemoony/snipkit/tree/main/themes) for some examples.
+::: tip Example themes
+You can have a look at the [built-in themes](https://github.com/lemoony/snipkit/tree/main/themes) for some examples.
+:::
 
-!!! tip "Dark & Light themes"
-    You can define themes differently for light & dark terminal backgrounds. Just add the suffix `.light.yaml` 
-    respectively `.dark.yaml` to the filename (e.g., `example-theme.light.yaml`). 
-    SnipKit will pick the appropriate theme automatically. 
+::: tip Dark & Light themes
+You can define themes differently for light & dark terminal backgrounds. Just add the suffix `.light.yaml` 
+respectively `.dark.yaml` to the filename (e.g., `example-theme.light.yaml`). 
+SnipKit will pick the appropriate theme automatically. 
+:::
 
 ### Variables
 
@@ -99,8 +102,9 @@ titleColor: "#FF0000"
 
 You can either use the hex value or an ANSI code to specify a color, e.g.: `#c0c0c0` or `7` for a light-gray color.
 
-!!! info "Implementation detail"
-    The underlying library used for the colors is [termenv](https://github.com/muesli/termenv). 
-    The [Readme](https://github.com/muesli/termenv#color-chart) gives a good overview of available ANSI colors.
+::: info Implementation detail
+The underlying library used for the colors is [termenv](https://github.com/muesli/termenv). 
+The [Readme](https://github.com/muesli/termenv#color-chart) gives a good overview of available ANSI colors.
+:::
 
-[configuration]: overview.md
+[configuration]: overview
diff --git a/docs/getting-started/fzf.md b/docs/getting-started/fzf.md
index ca603f73..a8d1739e 100644
--- a/docs/getting-started/fzf.md
+++ b/docs/getting-started/fzf.md
@@ -4,7 +4,7 @@ Snipkit can also be used with other tools to support your optimal workflow.
 
 For example, Snipkit snippets can be searched and executed via [fzf](https://github.com/junegunn/fzf) instead of using the built-in lookup tool. The following is an example script that first exports all snippets using snipkit export, selects one via fzf, and then executes the snippet using snipkit exec, also handling any necessary parameters.
 
-```sh title="sn.sh"
+```sh [sn.sh]
 #!/bin/bash
 
 # Function to check if a command is installed
diff --git a/docs/getting-started/overview.md b/docs/getting-started/overview.md
index 22782a87..a55cfa9f 100644
--- a/docs/getting-started/overview.md
+++ b/docs/getting-started/overview.md
@@ -37,69 +37,76 @@ Use "snipkit [command] --help" for more information about a command.
 
 Upon first usage, you have to create a config file.
 
-```sh title="Create a new config file"
+```sh [Create a new config file]
 snipkit config init
 ```
 
-!!! tip "Edit the config file manually"
-    SnipKit has a lot more configuration options. Please see [Configuration][configuration] if you encounter problems or want
-    to modify the behavior.
+::: tip Edit the config file manually
+SnipKit has a lot more configuration options. Please see [Configuration][configuration] if you encounter problems or want
+to modify the behavior.
+:::
 
 As of now, no external snippet manager is configured.
 
-```sh title="Add an external snippet manager"
+```sh [Add an external snippet manager]
 snipkit manager add
 ```
 
 You will be presented with a list of supported managers. Pick the one you want to use. After that, you should be ready to go.
 
-!!! tip "Different manager need different configuration"
-    Every manager has unique configuration options. Have a look at [Managers][managers] for more information.
+::: tip Different manager need different configuration
+Every manager has unique configuration options. Have a look at [Managers][managers] for more information.
+:::
 
-[configuration]: ../configuration/overview.md
-[managers]: ../managers/overview.md
+[configuration]: ../configuration/overview
+[managers]: ../managers/overview
 
 ## Snippet Commands
 
 #### Execute snippets
 
-```sh title="Execute a snippet"
+```sh [Execute a snippet]
 snipkit exec
 ```
 
-!!! tip "Confirm commands"
-    If you want to confirm a command before execution (with all parameters being resolved) add the 
-    flag `--confirm`:
-    ```bash 
-    snipkit exec --confirm
-    ```
-    Snipkit will print the command on stdout and ask you to explicitly confirm its execution.
+::: tip Confirm commands
+If you want to confirm a command before execution (with all parameters being resolved) add the 
+flag `--confirm`:
+```bash 
+snipkit exec --confirm
+```
+Snipkit will print the command on stdout and ask you to explicitly confirm its execution.
+:::
 
-!!! tip "Print snippet on stdout"
-    If you want to print the command that is executed add the flag `-p` or `--print`.
+::: tip Print snippet on stdout
+If you want to print the command that is executed add the flag `-p` or `--print`.
+:::
 
-!!! tip "Execute a snippet directly by ID"
-    A snippet can be executed directly without selecting it via the UI. See [Execute snippet by ID](#execute-snippet-by-id)
+::: tip Execute a snippet directly by ID
+A snippet can be executed directly without selecting it via the UI. See [Execute snippet by ID](#execute-snippet-by-id)
+:::
 
 #### Print snippets
 
 You can print snippets to stdout without executing them.
 
-```sh title="Print a snippet"
+```sh [Print a snippet]
 snipkit print
 ```
 
-!!! tip "Print and copy snippet"
-    Use `snipkit print --copy` to print the snippet and copy it to the clipboard at the same time.
+::: tip Print and copy snippet
+Use `snipkit print --copy` to print the snippet and copy it to the clipboard at the same time.
+:::
 
-!!! tip "Print snippet by ID"
-    The print command also supports the `id` and `param` flags. See [Execute snippet by ID](#execute-snippet-by-id). 
+::: tip Print snippet by ID
+The print command also supports the `id` and `param` flags. See [Execute snippet by ID](#execute-snippet-by-id). 
+:::
 
 #### Browse snippets
 
 You can browse all available snippets without executing or printing them.
 
-```sh title="Browse all snippets"
+```sh [Browse all snippets]
 snipkit browse
 ```
 
@@ -107,7 +114,7 @@ snipkit browse
 
 You can copy a snippet to the clipboard in two ways:
 
-```sh title="Copy to clipboard"
+```sh [Copy to clipboard]
 snipkit copy # Copies the snippet directly to the clipboard without printing
 snipkit print --copy # Prints the snippet on stdout and, additionally, copies it to the clipboard
 ```
diff --git a/docs/getting-started/parameters.md b/docs/getting-started/parameters.md
index 3ae65329..14c2eb89 100644
--- a/docs/getting-started/parameters.md
+++ b/docs/getting-started/parameters.md
@@ -2,17 +2,19 @@
 
 To support snippet parameters, SnipKit requires special parameter syntax in your scripts.
 
-!!! info 
-    The parameter syntax used by SnipKit ensures that your scripts remain fully functional even when not executed via SnipKit. All parameter information is described through comments, making it a consistent way to document your scripts.
+::: info
+The parameter syntax used by SnipKit ensures that your scripts remain fully functional even when not executed via SnipKit. All parameter information is described through comments, making it a consistent way to document your scripts.
+:::
 
-!!! tip 
-    [SnipKit Assistant][assistant] helps you write snippets using the correct parameter syntax.
+::: tip
+[SnipKit Assistant][assistant] helps you write snippets using the correct parameter syntax.
+:::
 
-[assistant]: ../assistant/index.md
+[assistant]: ../assistant/index
 
 ## Parameter Names & Descriptions
 
-```sh linenums="1" title="Example snippet"
+```sh:line-numbers [Example snippet]
 # some comment
 # ${VAR1} Name: First Output
 # ${VAR1} Description: What to print on the terminal first
@@ -28,15 +30,16 @@ used in your script (e.g., `VAR1` in the example).
   parameter input field.
 - Line 4 uses the parameter. It does not correspond to the parameter syntax and belongs to your script.
 
-!!! note "Default parameter name and type"
-    If you don't specify a parameter name, the name of the variable will be used instead, e.g., `VAR1` in the example.
-    In case you don't provide a type (e.g., `PASSWORD` or `PATH` - see below), the default is `TEXT`
+::: tip Default parameter name and type
+If you don't specify a parameter name, the name of the variable will be used instead, e.g., `VAR1` in the example.
+In case you don't provide a type (e.g., `PASSWORD` or `PATH` - see below), the default is `TEXT`
+:::
 
 ## Default Values
 
 You can define a default value for each parameter:
 
-```sh linenums="1" title="Example snippet with a parameter default value"
+```sh:line-numbers [Example snippet with a parameter default value]
 # some comment
 # ${VAR1} Default: Hello World!
 echo "${VAR1}"
@@ -48,7 +51,7 @@ This way, the input field for parameter `VAR1` will be automatically filled with
 
 You can add multiple pre-defined values for a parameter in order to ease filling the input form:
 
-```sh linenums="1" title="Example snippet with pre-defined values for a parameter"
+```sh:line-numbers [Example snippet with pre-defined values for a parameter]
 # some comment
 # ${VAR1} Values: One + some more, "Two",Three,  ,
 # ${VAR1} Values: Four\, and some more, Five
@@ -58,25 +61,26 @@ echo "${VAR1}"
 The example defines the values `One + some more`, `"Two"`, `Three`, `Four, and some more`, and `Five`. Empty pre-defined
 values will be omitted.
 
-![Demo](../images/param-example-predefined-values.gif)
+![Demo](/images/param-example-predefined-values.gif)
 
 You can define multiple lines starting with `${<varname>} Values:` to list pre-defined values. The listed values will be
 joined by SnipKit. Each value must be separated by the next via the character `,`.
 
-!!! attention 
-    If the value contains a comma itself, it needs to be escaped via `\,`.
+::: warning
+If the value contains a comma itself, it needs to be escaped via `\,`.
+:::
 
 ## Passwords
 
 A parameter can be marked to be a password. In this case, the actual characters of the input will be masked.
 
-```sh linenums="1" title="Example snippet with a PASSWORD parameter"
+```sh:line-numbers [Example snippet with a PASSWORD parameter]
 # ${PW} Name: Login password
 # ${PW} Type: PASSWORD
 login ${PW}
 ```
 
-![Demo](../images/param-example-password.gif)
+![Demo](/images/param-example-password.gif)
 
 Marking the parameter `PW` as password happens in line 2 by defining `Type: PASSWORD`.
 
@@ -85,13 +89,13 @@ Marking the parameter `PW` as password happens in line 2 by defining `Type: PASS
 Often, parameters are a path to a file or a directory. In this case, SnipKit is able to provide you with autocomplete
 suggestions:
 
-```sh linenums="1" title="Example snippet with a PATH parameters"
+```sh:line-numbers [Example snippet with a PATH parameters]
 # ${FILE} Name: File path
 # ${FILE} Type: PATH
 git ls-files "${FILE}" | xargs wc -l
 ```
 
-![Demo](../images/param-example-path.gif)
+![Demo](/images/param-example-path.gif)
 
 Marking the parameter `FILE` as path happens in line 2 by defining `Type: PATH`.
 
diff --git a/docs/getting-started/power-setup.md b/docs/getting-started/power-setup.md
index f75ccfbf..02fc9c2e 100644
--- a/docs/getting-started/power-setup.md
+++ b/docs/getting-started/power-setup.md
@@ -1,7 +1,8 @@
 # Power setup
 
-!!! tip "Customize Snipkit"
-    Also have a look at [fzf][fzf] to get an understanding of how to customize Snipkit even more to fit your needs.
+::: tip Customize Snipkit
+Also have a look at [fzf][fzf] to get an understanding of how to customize Snipkit even more to fit your needs.
+:::
 
 ### Alias
 
@@ -48,4 +49,4 @@ defaultRootCommand: "exec"
 With this setup, calling `sn` will yield the same result as `snipkit exec`. If you want to call
 the `print` command instead, type `sn print`.
 
-[fzf]: ./fzf.md
+[fzf]: ./fzf
diff --git a/docs/index.md b/docs/index.md
index d8838fae..562b09c2 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,24 +1,29 @@
 ---
-hide:
-- navigation
-- toc
+layout: home
+
+hero:
+  name: SnipKit
+  text: Execute scripts without leaving the terminal
+  tagline: Retrieve snippets from your favorite snippet manager, search by typing, and execute with parameters.
+  image:
+    src: /images/demo.gif
+    alt: SnipKit Demo
+  actions:
+    - theme: brand
+      text: Getting Started
+      link: /getting-started/overview
+    - theme: alt
+      text: View on GitHub
+      link: https://github.com/lemoony/snipkit
+
+features:
+  - icon: 🔍
+    title: Search Snippets
+    details: Search for snippets by typing. SnipKit supports fuzzy matching for quick access to your scripts.
+  - icon: ⚙️
+    title: Parameters
+    details: Execute snippets with parameters. Define default values or pick from pre-defined options.
+  - icon: 🤖
+    title: AI Assistant
+    details: Generate scripts with the help of AI using the SnipKit Assistant feature.
 ---
-
-# SnipKit
-
-![Demo](./images/demo.gif){ align=left }
-
-## Execute the scripts saved in your favorite snippet manager without even leaving the terminal.
-
-Retrieve snippets from a list of external snippet managers, so you can keep your scripts all at one place and manage 
-them more easily:
-
-* Search for snippets by typing.
-
-* Execute them with parameters. Define default values or a list of pre-defined values to pick from.
-
-* Use SnipKit Assistant to generate scripts with the help of AI.
-
-* Customize SnipKit with a theme to match the look of your terminal.
-
-[Getting started](./getting-started/overview.md){ .md-button .md-button--primary }
diff --git a/docs/managers/fslibrary.md b/docs/managers/fslibrary.md
index 39385357..e87a042a 100644
--- a/docs/managers/fslibrary.md
+++ b/docs/managers/fslibrary.md
@@ -9,7 +9,7 @@ files which correspond to snippets.
 
 The configuration for the file system library may look similar to this:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 manager:
   fsLibrary:
     # If set to false, the files specified via libraryPath will not be provided to you.
@@ -47,7 +47,7 @@ with `#` is after line 3, the snippet name will be ignored.
 
 E.g., a valid snippet named `Do something` instead of `example.sh` may look like this:
 
-```sh linenums="1" title="example.sh"
+```sh:line-numbers [example.sh]
 #!/bin/bash
 
 #
@@ -57,13 +57,15 @@ E.g., a valid snippet named `Do something` instead of `example.sh` may look like
 echo "here we go..."
 ```
 
-!!! attention "Open snippets lazily"
-    This only works if `lazyOpen` is set to false since the snippet files must be parsed in advance before presenting
-    the lookup window. If set to `true`, only the filename can be used as snippet name.
+::: warning Open snippets lazily
+This only works if `lazyOpen` is set to false since the snippet files must be parsed in advance before presenting
+the lookup window. If set to `true`, only the filename can be used as snippet name.
+:::
 
-!!! tip "Hide the title comment"
-    If you don't want to show the title header in the snippet preview window, set `hideTitleInPreview: true`.
-    SnipKit will remove the title header.
+::: tip Hide the title comment
+If you don't want to show the title header in the snippet preview window, set `hideTitleInPreview: true`.
+SnipKit will remove the title header.
+:::
 
 ## Assistant Configuration
 
@@ -71,7 +73,7 @@ The File System Library allows you to save scripts generated by the [SnipKit Ass
 
 If you have multiple library paths specified, the `assistantLibraryPathIndex` setting determines where the generated scripts will be saved. For example, via the following configuration, all generated scripts are saved in `/path/to/file/system/snipkit_assistant`:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 manager:
   fsLibrary:
     libraryPath:
@@ -81,4 +83,4 @@ manager:
     assistantLibraryPathIndex: 1
 ```
 
-[assistant]: ../assistant/index.md
+[assistant]: ../assistant/index
diff --git a/docs/managers/githubgist.md b/docs/managers/githubgist.md
index b8dc1bbc..1e19c517 100644
--- a/docs/managers/githubgist.md
+++ b/docs/managers/githubgist.md
@@ -5,15 +5,16 @@ Available for: macOS, Linux
 The GitHub Gist manager lets you provide snippets via multiple GitHub accounts. Each gist may contain multiple files which 
 are mapped to single snippets. The gists are cached locally and synchronized manually, so accessing them is very fast.
 
-!!! tip "Example Gist"
-    Upon adding the GitHub Gist manager via `snipkit manager add`, SnipKit will configure a working 
-    [example gist](https://gist.github.com/lemoony/4905e7468b8f0a7991d6122d7d09e40d), so you can quickly see how it works.
+::: tip Example Gist
+Upon adding the GitHub Gist manager via `snipkit manager add`, SnipKit will configure a working 
+[example gist](https://gist.github.com/lemoony/4905e7468b8f0a7991d6122d7d09e40d), so you can quickly see how it works.
+:::
 
 ## Configuration
 
 The configuration for the GitHub Gist manager may look similar to this:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 manager:
     githubGist:
       # If set to false, github gist is disabled completely.
@@ -73,17 +74,18 @@ After specifying the desired authentication mechanism, just trigger a synchroniz
 ask you for the PAT or perform the OAuth authorization. The access token will be stored securely (e.g., by means of Keychain 
 on macOS).
 
-!!! tip "PAT vs OAuth"
-    If you want to use a PAT or OAuth. Both mechanisms have different advantages. With a personalized access token, you have 
-    full control over the expiration date, but you have to create the token yourself. The OAuth mechanism is more convenient 
-    since you don't have to create a token yourself. However, the token may expire sooner and you have to perform the 
-    authentication process more often.
+::: tip PAT vs OAuth
+If you want to use a PAT or OAuth. Both mechanisms have different advantages. With a personalized access token, you have 
+full control over the expiration date, but you have to create the token yourself. The OAuth mechanism is more convenient 
+since you don't have to create a token yourself. However, the token may expire sooner and you have to perform the 
+authentication process more often.
+:::
 
 ### Custom OAuth Client ID
 
 One option which is not listed by default, since it won't be required very often, is the following:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 manager:
     githubGist:
       OAuthClientID: <client_id>
@@ -104,11 +106,12 @@ the following values:
 - `COMBINE_PREFER_DESCRIPTION`:  The description of the gist will be used as name. If a gist contains multiple files, 
     the description and the filename of the gist will be concatenated.
 
-!!! tip "Comment Syntax"
-    SnipKit lets you also provide a different snippet name via a special comment syntax. For a more detailed
-    description, please see section *Snippet Names* in [file system directory][fslibrary].
-    In order to enable this feature, set `titleHeaderEnabled` to `true`. If a snippet does not contain a title header
-    comment, the specified `nameMode` will decide the snippet name.
+::: tip Comment Syntax
+SnipKit lets you also provide a different snippet name via a special comment syntax. For a more detailed
+description, please see section *Snippet Names* in [file system directory][fslibrary].
+In order to enable this feature, set `titleHeaderEnabled` to `true`. If a snippet does not contain a title header
+comment, the specified `nameMode` will decide the snippet name.
+:::
 
 ## Tags
 
@@ -117,5 +120,5 @@ The description of a gist may contain multiple tags which can be used for filter
 E.g., a gist with the description `Example gist title #test #snipkit` is tagged with `test` and `snipkit`. 
 If you have set `removeTagsFromDescription` to `true`, only `Example gist title` will be used as Snippet Name.
 
-[fslibrary]: ./fslibrary.md
+[fslibrary]: ./fslibrary
 
diff --git a/docs/managers/overview.md b/docs/managers/overview.md
index 4baf73f3..b8a6f7db 100644
--- a/docs/managers/overview.md
+++ b/docs/managers/overview.md
@@ -32,7 +32,7 @@ be added to your config file, however, the manager will be disabled.
 
 Each manager can be enabled or disabled. By default, all managers are disabled:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 manager:
     <managerName>:
       # If set to false, the <managerName> is disabled 
@@ -43,5 +43,5 @@ If a manager does not work, SnipKit refuses to startup. In this case, disable th
 fix the configuration.
 
 
-[configuration]: ../configuration/overview.md
-[fslibrary]: ./fslibrary.md
+[configuration]: ../configuration/overview
+[fslibrary]: ./fslibrary
diff --git a/docs/managers/pet.md b/docs/managers/pet.md
index 035613e7..0865165e 100644
--- a/docs/managers/pet.md
+++ b/docs/managers/pet.md
@@ -8,7 +8,7 @@ Available for: macOS, Linux
 
 The configuration for Pet may look similar to this:
 
-```yaml title="config.yaml" 
+```yaml [config.yaml] 
 manager:
     pet:
       # Set to true if you want to use pet.
@@ -33,10 +33,11 @@ snippets will not be presented to you. If you don't want to filter for tags, set
 Pet comes with its own parameter syntax in the form of `<param>`, `<param=default_value>` or `<param=|_value1_||_value2_|>`. 
 SnipKit supports this syntax and you should have no problems using your Pet snippets the same way in SnipKit.
 
-!!! tip
-    While being easy to use, Pet's parameter syntax is less expressive than the one of SnipKit.
-    Migrate to the  [file system directory][fslibrary] manager if you want to take advantage of the additional SnipKit 
-    features like multiple value options or parameter descriptions.
+::: tip
+While being easy to use, Pet's parameter syntax is less expressive than the one of SnipKit.
+Migrate to the  [file system directory][fslibrary] manager if you want to take advantage of the additional SnipKit 
+features like multiple value options or parameter descriptions.
+:::
 
 
-[fslibrary]: ./fslibrary.md
+[fslibrary]: ./fslibrary
diff --git a/docs/managers/pictarinesnip.md b/docs/managers/pictarinesnip.md
index 8cb3b33d..e540763e 100644
--- a/docs/managers/pictarinesnip.md
+++ b/docs/managers/pictarinesnip.md
@@ -10,7 +10,7 @@ Available for: macOS
 
 The configuration for Snip may look similar to this:
 
-```yaml title="config.yaml" 
+```yaml [config.yaml] 
 manager:
     pictarineSnip:
       # Set to true if you want to use Snip.
diff --git a/docs/managers/snippetslab.md b/docs/managers/snippetslab.md
index b1ca82a8..55bb0305 100644
--- a/docs/managers/snippetslab.md
+++ b/docs/managers/snippetslab.md
@@ -8,7 +8,7 @@ Available for: macOS
 
 The configuration for SnippetsLab may look similar to this:
 
-```yaml title="config.yaml"
+```yaml [config.yaml]
 manager:
     snippetsLab:
       # Set to true if you want to use SnippetsLab.
diff --git a/docs/images/assistant/assistant-choose.gif b/docs/public/images/assistant/assistant-choose.gif
similarity index 100%
rename from docs/images/assistant/assistant-choose.gif
rename to docs/public/images/assistant/assistant-choose.gif
diff --git a/docs/images/assistant/assistant-save.gif b/docs/public/images/assistant/assistant-save.gif
similarity index 100%
rename from docs/images/assistant/assistant-save.gif
rename to docs/public/images/assistant/assistant-save.gif
diff --git a/docs/images/assistant/assistant-zip.gif b/docs/public/images/assistant/assistant-zip.gif
similarity index 100%
rename from docs/images/assistant/assistant-zip.gif
rename to docs/public/images/assistant/assistant-zip.gif
diff --git a/docs/images/assistant/assistant.gif b/docs/public/images/assistant/assistant.gif
similarity index 100%
rename from docs/images/assistant/assistant.gif
rename to docs/public/images/assistant/assistant.gif
diff --git a/docs/images/demo.gif b/docs/public/images/demo.gif
similarity index 100%
rename from docs/images/demo.gif
rename to docs/public/images/demo.gif
diff --git a/docs/images/logo.png b/docs/public/images/logo.png
similarity index 100%
rename from docs/images/logo.png
rename to docs/public/images/logo.png
diff --git a/docs/images/param-example-password.gif b/docs/public/images/param-example-password.gif
similarity index 100%
rename from docs/images/param-example-password.gif
rename to docs/public/images/param-example-password.gif
diff --git a/docs/images/param-example-path.gif b/docs/public/images/param-example-path.gif
similarity index 100%
rename from docs/images/param-example-path.gif
rename to docs/public/images/param-example-path.gif
diff --git a/docs/images/param-example-predefined-values.gif b/docs/public/images/param-example-predefined-values.gif
similarity index 100%
rename from docs/images/param-example-predefined-values.gif
rename to docs/public/images/param-example-predefined-values.gif
diff --git a/docs/images/themes/default-dark-form.png b/docs/public/images/themes/default-dark-form.png
similarity index 100%
rename from docs/images/themes/default-dark-form.png
rename to docs/public/images/themes/default-dark-form.png
diff --git a/docs/images/themes/default-dark-lookup.png b/docs/public/images/themes/default-dark-lookup.png
similarity index 100%
rename from docs/images/themes/default-dark-lookup.png
rename to docs/public/images/themes/default-dark-lookup.png
diff --git a/docs/images/themes/default-light-form.png b/docs/public/images/themes/default-light-form.png
similarity index 100%
rename from docs/images/themes/default-light-form.png
rename to docs/public/images/themes/default-light-form.png
diff --git a/docs/images/themes/default-light-lookup.png b/docs/public/images/themes/default-light-lookup.png
similarity index 100%
rename from docs/images/themes/default-light-lookup.png
rename to docs/public/images/themes/default-light-lookup.png
diff --git a/docs/images/themes/simple-form.png b/docs/public/images/themes/simple-form.png
similarity index 100%
rename from docs/images/themes/simple-form.png
rename to docs/public/images/themes/simple-form.png
diff --git a/docs/images/themes/simple-lookup.png b/docs/public/images/themes/simple-lookup.png
similarity index 100%
rename from docs/images/themes/simple-lookup.png
rename to docs/public/images/themes/simple-lookup.png
diff --git a/docs/public/versions.json b/docs/public/versions.json
new file mode 100644
index 00000000..c7c3047d
--- /dev/null
+++ b/docs/public/versions.json
@@ -0,0 +1,77 @@
+[
+  {
+    "version": "dev",
+    "title": "dev",
+    "aliases": []
+  },
+  {
+    "version": "v1.7.0",
+    "title": "v1.7.0",
+    "aliases": ["latest"]
+  },
+  {
+    "version": "v1.6.1",
+    "title": "v1.6.1",
+    "aliases": []
+  },
+  {
+    "version": "v1.6.0",
+    "title": "v1.6.0",
+    "aliases": []
+  },
+  {
+    "version": "v1.5.0",
+    "title": "v1.5.0",
+    "aliases": []
+  },
+  {
+    "version": "v1.4.3",
+    "title": "v1.4.3",
+    "aliases": []
+  },
+  {
+    "version": "v1.4.2",
+    "title": "v1.4.2",
+    "aliases": []
+  },
+  {
+    "version": "v1.4.1",
+    "title": "v1.4.1",
+    "aliases": []
+  },
+  {
+    "version": "v1.4.0",
+    "title": "v1.4.0",
+    "aliases": []
+  },
+  {
+    "version": "v1.3.2",
+    "title": "v1.3.2",
+    "aliases": []
+  },
+  {
+    "version": "v1.3.1",
+    "title": "v1.3.1",
+    "aliases": []
+  },
+  {
+    "version": "v1.3.0",
+    "title": "v1.3.0",
+    "aliases": []
+  },
+  {
+    "version": "v1.2.0",
+    "title": "v1.2.0",
+    "aliases": []
+  },
+  {
+    "version": "v1.1.0",
+    "title": "v1.1.0",
+    "aliases": []
+  },
+  {
+    "version": "v1.0.0",
+    "title": "v1.0.0",
+    "aliases": []
+  }
+]
diff --git a/mkdocs.yml b/mkdocs.yml
index 6b629a0a..b17feb08 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -8,7 +8,7 @@ site_description: >-
 repo_name: lemoony/snipkit
 repo_url: https://github.com/lemoony/snipkit
 
-copyright: Copyright &copy; 2024 lemoony
+copyright: Copyright &copy; 2026 lemoony
 
 theme:
   name: material
@@ -31,27 +31,26 @@ markdown_extensions:
   - attr_list
   - md_in_html
 nav:
-  - Home: 'index.md'
+  - Home: "index.md"
   - Getting started:
-    - Overview: 'getting-started/overview.md'
-    - Parameters: 'getting-started/parameters.md'
-    - Power Setup: 'getting-started/power-setup.md'
-    - Fzf: 'getting-started/fzf.md'
+      - Overview: "getting-started/overview.md"
+      - Parameters: "getting-started/parameters.md"
+      - Power Setup: "getting-started/power-setup.md"
+      - Fzf: "getting-started/fzf.md"
   - Configuration:
-      - Overview: 'configuration/overview.md'
-      - Themes: 'configuration/themes.md'
+      - Overview: "configuration/overview.md"
+      - Themes: "configuration/themes.md"
   - Managers:
-    - Overview: 'managers/overview.md'
-    - File System Library: 'managers/fslibrary.md'
-    - GitHub Gist: 'managers/githubgist.md'
-    - SnippetsLab: 'managers/snippetslab.md'
-    - Snip: 'managers/pictarinesnip.md'
-    - Pet: 'managers/pet.md'
+      - Overview: "managers/overview.md"
+      - File System Library: "managers/fslibrary.md"
+      - GitHub Gist: "managers/githubgist.md"
+      - SnippetsLab: "managers/snippetslab.md"
+      - Snip: "managers/pictarinesnip.md"
+      - Pet: "managers/pet.md"
   - Assistant:
-    - Overview: 'assistant/index.md'
-    - OpenAI: 'assistant/openai.md'
-    - Anthropic: 'assistant/anthropic.md'
-    - Gemini: 'assistant/gemini.md'
-    - Ollama: 'assistant/ollama.md'
-    - OpenAI-Compatible: 'assistant/openai-compatible.md'
-
+      - Overview: "assistant/index.md"
+      - OpenAI: "assistant/openai.md"
+      - Anthropic: "assistant/anthropic.md"
+      - Gemini: "assistant/gemini.md"
+      - Ollama: "assistant/ollama.md"
+      - OpenAI-Compatible: "assistant/openai-compatible.md"
diff --git a/package.json b/package.json
new file mode 100644
index 00000000..74ac3bb2
--- /dev/null
+++ b/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "snipkit-docs",
+  "type": "module",
+  "scripts": {
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
+  },
+  "devDependencies": {
+    "@catppuccin/vitepress": "^0.1.2",
+    "glob": "^11.0.0",
+    "vitepress": "^1.5.0",
+    "vue": "^3.5.0"
+  }
+}
diff --git a/scripts/update-versions.js b/scripts/update-versions.js
new file mode 100644
index 00000000..f07b5ee0
--- /dev/null
+++ b/scripts/update-versions.js
@@ -0,0 +1,58 @@
+import fs from 'fs'
+import path from 'path'
+
+// Usage: node scripts/update-versions.js <version> <type> [latest]
+// Example: node scripts/update-versions.js v1.7.0 vitepress latest
+// Example: node scripts/update-versions.js dev vitepress
+
+const args = process.argv.slice(2)
+if (args.length < 2) {
+  console.error('Usage: node scripts/update-versions.js <version> <type> [latest]')
+  console.error('Example: node scripts/update-versions.js v1.7.0 vitepress latest')
+  process.exit(1)
+}
+
+const [version, type, ...aliases] = args
+const versionsPath = path.join(process.cwd(), 'versions.json')
+
+let versions = []
+if (fs.existsSync(versionsPath)) {
+  versions = JSON.parse(fs.readFileSync(versionsPath, 'utf8'))
+}
+
+// Remove 'latest' alias from all existing versions if we're setting a new latest
+if (aliases.includes('latest')) {
+  versions = versions.map(v => ({
+    ...v,
+    aliases: (v.aliases || []).filter(a => a !== 'latest')
+  }))
+}
+
+// Find or create version entry
+const existingIndex = versions.findIndex(v => v.version === version)
+const newEntry = {
+  version,
+  title: version,
+  aliases: aliases,
+  type: type
+}
+
+if (existingIndex >= 0) {
+  versions[existingIndex] = newEntry
+} else {
+  // Insert at appropriate position
+  // dev always first, then by version number descending
+  if (version === 'dev') {
+    versions.unshift(newEntry)
+  } else {
+    // Find insertion point after dev but sorted by version
+    let insertIndex = versions.findIndex(v => v.version !== 'dev')
+    if (insertIndex === -1) insertIndex = versions.length
+
+    // Insert and sort non-dev versions
+    versions.splice(insertIndex, 0, newEntry)
+  }
+}
+
+fs.writeFileSync(versionsPath, JSON.stringify(versions, null, 2) + '\n')
+console.log(`Updated versions.json with ${version} (type: ${type}, aliases: ${aliases.join(', ') || 'none'})`)