or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

build-dev.mdcli.mdclient-api.mdconfiguration.mdindex.mdmarkdown.mdtheming.md
tile.json

tessl/npm-vitepress

Vite & Vue powered static site generator with Vue-based theming and markdown processing

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/vitepress@1.6.x

To install, run

npx @tessl/cli install tessl/npm-vitepress@1.6.0

index.mddocs/

VitePress

VitePress is a Vite & Vue powered static site generator that combines modern development experience with powerful content authoring capabilities. It provides a fast development server with hot module replacement, static site generation for production, Vue-based theming system, and enhanced markdown processing with Vue component support.

Package Information

  • Package Name: vitepress
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install vitepress

Core Imports

import { defineConfig, build, createServer, serve } from "vitepress";

For client-side usage:

import { useData, useRoute, useRouter, withBase } from "vitepress/client";

For theming:

import DefaultTheme from "vitepress/theme";

CommonJS (Node.js APIs only):

const { defineConfig, build, createServer, serve } = require("vitepress");

Basic Usage

// .vitepress/config.ts
import { defineConfig } from "vitepress";

export default defineConfig({
  title: "My Documentation Site",
  description: "A VitePress powered documentation site",
  themeConfig: {
    nav: [
      { text: "Guide", link: "/guide/" },
      { text: "API", link: "/api/" }
    ],
    sidebar: {
      "/guide/": [
        {
          text: "Introduction",
          items: [
            { text: "Getting Started", link: "/guide/getting-started" },
            { text: "Configuration", link: "/guide/configuration" }
          ]
        }
      ]
    }
  }
});

// Build for production
import { build } from "vitepress";
await build();

// Development server
import { createServer } from "vitepress";
const server = await createServer();
await server.listen();

Architecture

VitePress is built around several key components:

  • Configuration System: Type-safe configuration with defineConfig helpers supporting themes, markdown options, and site metadata
  • Development Server: Vite-powered dev server with HMR, Vue component support in markdown, and fast rebuilds
  • Build System: Static site generation with optimized bundle splitting, pre-rendering, and SEO-friendly output
  • Theming Engine: Vue-based theme system with default theme components, composables for state management, and full customization support
  • Markdown Processor: Enhanced markdown with Vue component embedding, syntax highlighting, custom containers, and frontmatter processing
  • Client Runtime: SPA-like navigation with data loading, routing utilities, and reactive state management

Capabilities

Configuration Management

Type-safe configuration system with helper functions and comprehensive theme configuration options. Supports extending configurations, multi-locale setups, and Vite integration.

function defineConfig<ThemeConfig = any>(
  config: UserConfig<ThemeConfig>
): UserConfig<ThemeConfig>;

function resolveConfig(
  root?: string,
  command?: "serve" | "build",
  mode?: string
): Promise<SiteConfig>;

interface UserConfig<ThemeConfig = any> {
  extends?: UserConfig<ThemeConfig>;
  base?: string;
  title?: string;
  description?: string;
  themeConfig?: ThemeConfig;
  markdown?: MarkdownOptions;
  vite?: UserConfig;
  locales?: LocaleConfig<ThemeConfig>;
}

Configuration

Build and Development

Build system for production static sites and development server with hot reloading. Includes preview server for testing built sites and various build optimization options.

function build(
  root?: string,
  buildOptions?: BuildOptions
): Promise<void>;

function createServer(
  root?: string,
  serverOptions?: ServerOptions
): Promise<ViteDevServer>;

function serve(options?: ServeOptions): Promise<void>;

interface BuildOptions {
  base?: string;
  outDir?: string;
  mpa?: boolean;
}

Build and Development

Client-Side API

Client-side composables and utilities for accessing VitePress runtime data, navigation, and page information. Essential for custom themes and Vue components in markdown.

function useData<T = any>(): VitePressData<T>;
function useRouter(): Router;
function useRoute(): Route;
function withBase(path: string): string;

interface VitePressData<T> {
  site: Ref<SiteData<T>>;
  page: Ref<PageData>;
  theme: Ref<T>;
  frontmatter: Ref<Record<string, any>>;
  title: Ref<string>;
  description: Ref<string>;
  isDark: Ref<boolean>;
}

Client-Side API

Theme System

Vue-based theming with default theme components, sidebar and navigation management, and comprehensive customization options. Includes composables for theme state and UI components.

interface Theme {
  Layout?: Component;
  enhanceApp?: (ctx: EnhanceAppContext) => void;
  extends?: Theme;
}

interface EnhanceAppContext {
  app: App;
  router: Router;
  siteData: Ref<SiteData>;
}

// Default theme composables
function useSidebar(): DefaultTheme.DocSidebar;
function useLocalNav(): DefaultTheme.DocLocalNav;

Theme System

Markdown Processing

Enhanced markdown processing with Vue component support, syntax highlighting, custom containers, and frontmatter parsing. Includes extensible plugin system and custom renderers.

function createMarkdownRenderer(
  options?: MarkdownOptions,
  base?: string,
  logger?: Logger
): MarkdownIt;

interface MarkdownOptions {
  lineNumbers?: boolean;
  config?: (md: MarkdownIt) => void;
  theme?: ThemeOptions;
  languages?: LanguageInput[];
  externalLinks?: Record<string, string>;
}

Markdown Processing

Command-Line Interface

Complete CLI for project initialization, development, building, and preview. Supports various options for customization and deployment workflows.

// CLI commands
vitepress [dev] [root]     // Start development server
vitepress build [root]     // Build for production  
vitepress preview [root]   // Preview built site
vitepress init [root]      // Initialize new project

// Programmatic CLI access
function init(root?: string): Promise<void>;
function scaffold(options: ScaffoldOptions): string;

Command-Line Interface

Types

interface SiteData<ThemeConfig = any> {
  base: string;
  lang: string;
  title: string;
  description: string;
  head: HeadConfig[];
  themeConfig: ThemeConfig;
  locales: LocaleConfig<ThemeConfig>;
  appearance: boolean | string | object;
  router: { prefetchLinks: boolean };
}

interface PageData {
  title: string;
  description: string;
  relativePath: string;
  headers: Header[];
  frontmatter: Record<string, any>;
  lastUpdated?: number;
}

interface Header {
  level: number;
  title: string;
  slug: string;
  link: string;
  children: Header[];
}

type HeadConfig = 
  | [string, Record<string, string>] 
  | [string, Record<string, string>, string];

type LocaleConfig<ThemeConfig = any> = Record<
  string, 
  LocaleSpecificConfig<ThemeConfig> & { 
    label: string; 
    link?: string; 
  }
>;

type Awaitable<T> = T | PromiseLike<T>;