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
├── cli/
│   ├── index.md
│   ├── installation.md
│   ├── sdk.md
│   └── vault.md
├── 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.

Using the Python CLI

bash

# Requires CLI dependencies installed
pip install socket0-sdk[cli]

# Start docs server (requires npm to be installed)
s0 sdk docs

# Custom port
s0 sdk docs --port 9000

Edit Documentation

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

Example:

docs/installation.md → http://localhost:5173/installation
docs/cli/sdk.md → http://localhost:5173/cli/sdk

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' },
      ],
    },
  ],
  '/cli/': [
    // CLI section...
  ],
}

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
:::

Links

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

Create markdown file in docs/:
bash
```
docs/new-section/page-name.md
```
1

Update sidebar in .vitepress/config.ts:

typescript

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

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.

Search

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

Connect GitHub repository
Set build command: npm run docs:build
Set publish directory: docs/.vitepress/dist
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
s0 sdk docs --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

Start dev server: s0 sdk docs or npm run docs:dev
Edit markdown files in docs/
See changes instantly in browser
Preview before building: npm run docs:preview

For Deployment

Update docs in docs/ directory
Test locally: npm run docs:build && npm run docs:preview
Commit changes
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:

Aspect	MkDocs	VitePress
Config	`mkdocs.yml` (YAML)	`.vitepress/config.ts` (TypeScript)
Markdown	Standard + plugins	Standard + extensions
Theme	Material	Default + customizable
Dev Server	Port 8000	Port 5173
Build Output	`site/`	`docs/.vitepress/dist/`
Language	Python-based	Node.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

VitePress Documentation Setup Guide ​

Overview ​

Why VitePress? ​

Installation ​

Prerequisites ​

First-Time Setup ​

Project Structure ​

Development ​

Start Development Server ​

Using the Python CLI ​

Edit Documentation ​

Building ​

Production Build ​

Preview Built Site ​

Configuration ​

Main Config: .vitepress/config.ts ​

Sidebar Navigation ​

Front Matter ​

Markdown Features ​

Code Highlighting ​

Containers ​

Links ​

Tables ​

Line Numbers ​

Customization ​

Add New Page ​

Add Navigation Items ​

Custom CSS ​

Custom Components ​

Search ​

Deployment ​

Static Hosting ​

GitHub Pages ​

Netlify ​

Troubleshooting ​

npm not found ​

Port already in use ​

Dependencies outdated ​

Build fails ​

Hot reload not working ​

Development Workflow ​

For Documentation ​

For Deployment ​

Advanced Configuration ​

Environment Variables ​

Build Options ​

SEO ​

Migration from MkDocs ​

Resources ​

Next Steps ​

VitePress Documentation Setup Guide

Overview

Why VitePress?

Installation

Prerequisites

First-Time Setup

Project Structure

Development

Start Development Server

Using the Python CLI

Edit Documentation

Building

Production Build

Preview Built Site

Configuration

Main Config: `.vitepress/config.ts`

Sidebar Navigation

Front Matter

Markdown Features

Code Highlighting

Containers

Links

Tables

Line Numbers

Customization

Add New Page

Add Navigation Items

Custom CSS

Custom Components

Search

Deployment

Static Hosting

GitHub Pages

Netlify

Troubleshooting

npm not found

Port already in use

Dependencies outdated

Build fails

Hot reload not working

Development Workflow

For Documentation

For Deployment

Advanced Configuration

Environment Variables

Build Options

SEO

Migration from MkDocs

Resources

Next Steps