VitePress

Appearance

VitePress Documentation Setup Guide ​

This guide explains how the Socket0 Python SDK documentation has been migrated from MkDocs to VitePress and how to use it.

Overview ​

VitePress is a static site generator built on Vite and Vue 3. It's faster, more modern, and provides a better developer experience compared to MkDocs.

Why VitePress? ​

  • ⚡ Lightning-fast - Built on Vite with instant server start and HMR
  • 🎨 Modern UI - Beautiful default theme with customization options
  • 📱 Responsive - Works great on desktop, tablet, and mobile
  • 🔍 Full-text search - Built-in search without external dependencies
  • 🚀 Production-ready - Optimized builds and deployment

Installation ​

Prerequisites ​

  • Node.js 18.0+ (download)
  • npm 9.0+ (comes with Node.js)

First-Time Setup ​

bash
# Install dependencies
npm install

# Verify installation
npm run docs:dev --help

Project Structure ​

.vitepress/
├── config.ts              # VitePress configuration
└── theme/
    └── index.ts           # Theme customization

docs/
├── index.md              # Homepage
├── installation.md       # Installation guide
├── contributing.md       # Contributing guide
├── vault/
│   ├── index.md
│   └── getting-started.md
└── api/
    └── index.md

package.json               # Node.js dependencies

Development ​

Start Development Server ​

bash
# Default port 5173
npm run docs:dev

# Custom port
npm run docs:dev -- --port 3000

Visit http://localhost:5173 in your browser. The site automatically reloads when you edit markdown files.

Edit Documentation ​

  1. Edit markdown files in docs/ directory
  2. Changes appear instantly in the browser (hot reload)
  3. File structure in docs/ automatically maps to URLs

Example:

  • docs/installation.md → http://localhost:5173/installation
  • docs/vault/getting-started.md → http://localhost:5173/vault/getting-started

Building ​

Production Build ​

bash
npm run docs:build

Output is in docs/.vitepress/dist/ - ready for deployment.

Preview Built Site ​

bash
npm run docs:preview

Configuration ​

Main Config: .vitepress/config.ts ​

Controls site-wide settings:

typescript
{
  title: 'Socket0 Python SDK',           // Browser tab title
  description: '...',                     // Meta description
  base: '/',                              // Base URL
  themeConfig: {
    logo: '/logo.svg',                   // Top-left logo
    nav: [...],                          // Top navigation
    sidebar: {...},                      // Left sidebar navigation
    socialLinks: [...],                  // Footer social links
  }
}

Sidebar is configured in .vitepress/config.ts:

typescript
sidebar: {
  '/vault/': [
    {
      text: 'Vault',
      items: [
        { text: 'Overview', link: '/vault/' },
        { text: 'Getting Started', link: '/vault/getting-started' },
      ],
    },
  ],
}

Update this when adding new pages.

Front Matter ​

Add metadata to markdown files using YAML front matter:

markdown
---
title: Custom Page Title
description: Page description for SEO
layout: home              # Special layout for home page
---

# Page Content

Home page uses special home layout with hero and features:

markdown
---
layout: home

hero:
  name: "Project Name"
  text: "Tagline"
  actions:
    - theme: brand
      text: "Get Started"
      link: /guide

features:
  - icon: 🎯
    title: "Feature"
    details: "Description"
---

Markdown Features ​

VitePress supports standard markdown plus extensions:

Code Highlighting ​

python
# docs/example.md
def hello():
    print("world")

Syntax highlighting works automatically for Python and other languages.

Containers ​

markdown
::: info
This is an info box
:::

::: warning
This is a warning
:::

::: danger
This is a danger box
:::

::: details Click me to view code
def example():
    pass
:::
markdown
# Absolute links
[Text](/path/to/page)

# Relative links
[Text](./relative/path)

# External links
[Text](https://example.com)

Tables ​

markdown
| Header 1 | Header 2 |
|----------|----------|
| Cell 1   | Cell 2   |
| Cell 3   | Cell 4   |

Line Numbers ​

Enabled by default in code blocks:

python
def function():
    return True

Customization ​

Add New Page ​

  1. Create markdown file in docs/:

    bash
    docs/new-section/page-name.md

  2. Update sidebar in .vitepress/config.ts:

    typescript
    sidebar: {
  '/new-section/': [
    {
      text: 'Section',
      items: [
        { text: 'Page', link: '/new-section/page-name' },
      ],
    },
  ],
}

Add Navigation Items ​

Edit .vitepress/config.ts:

typescript
nav: [
  { text: 'Home', link: '/' },
  { text: 'New Item', link: '/new-page' },
  {
    text: 'Dropdown',
    items: [
      { text: 'Item 1', link: '/item1' },
      { text: 'Item 2', link: '/item2' },
    ],
  },
]

Custom CSS ​

Add to .vitepress/theme/index.ts:

typescript
import DefaultTheme from 'vitepress/theme'
import './custom.css'

export default {
  extends: DefaultTheme,
}

Create .vitepress/theme/custom.css with custom styles.

Custom Components ​

Create Vue components in .vitepress/components/ and use in markdown:

markdown
<MyComponent />

VitePress automatically registers components.

Full-text search is built-in using local search provider. Configure in .vitepress/config.ts:

typescript
search: {
  provider: 'local',
}

Search indexes all pages automatically during build.

Deployment ​

Static Hosting ​

VitePress generates static HTML. Deploy the docs/.vitepress/dist/ folder to:

  • GitHub Pages
  • Netlify
  • Vercel
  • AWS S3
  • Any static hosting service

GitHub Pages ​

bash
# Build the site
npm run docs:build

# The dist/ folder contains the built site
# Push to GitHub and configure GitHub Pages to use the dist/ folder

Netlify ​

  1. Connect GitHub repository
  2. Set build command: npm run docs:build
  3. Set publish directory: docs/.vitepress/dist
  4. Deploy!

Troubleshooting ​

npm not found ​

Install Node.js from https://nodejs.org/

bash
# Verify installation
node --version
npm --version

Port already in use ​

bash
# Use custom port
npm run docs:dev -- --port 3000

Dependencies outdated ​

bash
# Update dependencies
npm update

# Or install latest versions
npm install vitepress@latest

Build fails ​

bash
# Clear cache and rebuild
rm -rf node_modules package-lock.json
npm install
npm run docs:build

Hot reload not working ​

bash
# Restart dev server
npm run docs:dev

# Or use different port
npm run docs:dev -- --port 3001

Development Workflow ​

For Documentation ​

  1. Start dev server: npm run docs:dev
  2. Edit markdown files in docs/
  3. See changes instantly in browser
  4. Preview before building: npm run docs:preview

For Deployment ​

  1. Update docs in docs/ directory
  2. Test locally: npm run docs:build && npm run docs:preview
  3. Commit changes
  4. Push to GitHub (auto-deploy on GitHub Pages)

Advanced Configuration ​

Environment Variables ​

Create .env in project root:

VITE_API_URL=https://api.example.com

Access in pages using import.meta.env.VITE_API_URL.

Build Options ​

Customize build in .vitepress/config.ts:

typescript
export default defineConfig({
  build: {
    minify: 'terser',
    chunkSizeWarningLimit: 500,
  },
})

SEO ​

Add meta tags in .vitepress/config.ts:

typescript
head: [
  ['meta', { name: 'og:title', content: 'Socket0 Python SDK' }],
  ['meta', { name: 'og:description', content: 'Description' }],
  ['meta', { name: 'og:image', content: 'https://example.com/og.png' }],
]

Migration from MkDocs ​

Changes made in this migration:

AspectMkDocsVitePress
Configmkdocs.yml (YAML).vitepress/config.ts (TypeScript)
MarkdownStandard + pluginsStandard + extensions
ThemeMaterialDefault + customizable
Dev ServerPort 8000Port 5173
Build Outputsite/docs/.vitepress/dist/
LanguagePython-basedNode.js-based

Resources ​

Next Steps ​

  • Edit docs and see live updates
  • Customize theme in .vitepress/theme/custom.css
  • Add new pages and update sidebar navigation
  • Deploy to your hosting provider