Creating and Running a VitePress Project with ServBay

VitePress is a modern static site generator powered by Vue, designed to build fast, visually appealing, and easy-to-maintain documentation websites. Built on top of Vite, it delivers an excellent development experience and superior build performance. If you need to create professional documentation for your projects, libraries, or products, VitePress is an outstanding choice.

Reliable and flexible local web development environments are crucial when developing and testing VitePress sites locally. ServBay is tailored for this need—a streamlined solution that integrates multiple Node.js versions and powerful web servers (like Caddy or Nginx) so you can effortlessly serve your VitePress projects.

This guide walks you through setting up, configuring, and running a VitePress project from scratch in ServBay’s integrated environment, including setting up reverse proxy for the development server and serving static files for production builds.

What Is VitePress?

VitePress is a static site generator (SSG) built on Vite, harnessing the powerful capabilities of Vue 3 and the blazing-fast performance of Vite to create static websites—particularly technical documentation sites.

Key Features & Advantages of VitePress

• Lightning-fast Development: Enjoy hot module replacement (HMR) powered by Vite, allowing you to see changes nearly instantly in your browser and greatly boosting development efficiency.
• Vue-Powered: Directly use Vue components within Markdown files for richer interactivity and presentation.
• Simple & Intuitive: Minimal configuration—get started right away and focus on writing content.
• High Performance: Produces lightweight static files for rapid loading, plus built-in client-side routing for seamless single-page app experiences.
• SEO Friendly: Generates HTML structures optimized for search engines, with support for custom head tags.
• Enhanced Markdown: Supports all CommonMark and GitHub Flavored Markdown (GFM) features, plus extra syntax goodies.

With VitePress, developers can effortlessly build high-quality, high-performance documentation websites.

Creating and Running a VitePress Project with ServBay

ServBay makes managing Node.js versions and configuring web servers for your VitePress project easy—whether you’re running a local server for development or serving static files for production.

Prerequisites

Before you begin:

1. Install ServBay: Make sure ServBay is installed on your system. Refer to the ServBay Installation Guide.
2. Install the Node.js Package: Within ServBay, confirm you’ve installed and enabled the required Node.js version(s). Use the "Packages" page in ServBay’s dashboard for management. See Using Node.js.

Create a VitePress Project

1. Initialize Your Project Directory

   Open your terminal application. It’s recommended to create your project folder in ServBay’s default web root directory to simplify later configuration.

   macOS:

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

   Windows:

   cd C:\ServBay\www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app

2. Install VitePress and Initialize Configuration

   Inside your servbay-vitepress-app directory, use npm or yarn to install VitePress as a dev dependency, then run the initialization command.

   npm add -D vitepress
   npx vitepress init

   Or with Yarn:

   yarn add -D vitepress
   yarn vitepress init

   The initialization prompts you for basic settings like site title and description. Follow the prompts:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # Default docs directory—just press Enter
    │
    ◇  Site title:
    │  ServBay VitePress Demo # Enter your site title, e.g., ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # Enter your site description
    │
    ◇  Theme:
    │  Default Theme # Choose the default theme
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # Select based on your preference
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # Recommend choosing Yes to add scripts
    │
    └  Done! Now run npm run docs:dev and start writing.

   After initialization, VitePress creates a docs subdirectory under servbay-vitepress-app and generates default configuration files (.vitepress) plus sample pages (index.md, guide/index.md, etc.). Your package.json is updated with scripts like docs:dev and docs:build.

Edit Your VitePress Content

1. Edit the Homepage

   VitePress’s default homepage is at docs/index.md. You can open this file in any text editor and modify its content. For example:

   # Hello ServBay!
   
   Welcome to ServBay for running your VitePress documentation site.
   
   This is a local demo site created with VitePress and served via ServBay.

Start Development Mode

During development, it’s common to use VitePress’s built-in dev server for hot reloading and instant preview. With ServBay’s reverse proxy, you can access your dev server using a custom domain and enjoy SSL encryption.

1. Run the VitePress Development Server

   In your terminal, ensure you’re in the project root (/Applications/ServBay/www/servbay-vitepress-app on macOS or C:\ServBay\www\servbay-vitepress-app on Windows). Start the dev server and specify a port (e.g., 8585).

   npm run docs:dev -- --port 8585

   Or with Yarn:

   yarn docs:dev --port 8585

   The dev server starts and listens on the specified port, e.g., 8585. The terminal will show the local address, usually http://localhost:8585.

2. Configure ServBay Website (Reverse Proxy)

   Open the ServBay control panel and go to the "Sites" section. Add a new site configuration:

   • Name: e.g., VitePress Development Site
   • Domain: Enter the local development domain you’d like to use. To follow ServBay’s naming and avoid conflicts, use .servbay.demo, e.g., vitepress-dev.servbay.demo.
   • Site Type: Choose Reverse Proxy.
   • IP: Enter 127.0.0.1 (localhost).
   • Port: Enter the port you set earlier, e.g., 8585.

   Save and apply. ServBay will automatically configure its web server (either Caddy or Nginx) so requests to https://vitepress-dev.servbay.demo are forwarded to http://127.0.0.1:8585.

3. Access Your Dev Site

   You can now visit your configured domain, https://vitepress-dev.servbay.demo, in your browser. You’ll see your VitePress-powered site in development mode—complete with custom domain and SSL certificate issued by ServBay User CA for secure HTTPS access.

Build the Production Version

When your VitePress docs are finalized for release, you’ll want to build an optimized static version.

1. Build for Production

   In the terminal, make sure you’re in the project root (/Applications/ServBay/www/servbay-vitepress-app on macOS or C:\ServBay\www\servbay-vitepress-app on Windows), then run:

   npm run docs:build

   Or with Yarn:

   yarn docs:build

   This compiles and packages your Markdown, Vue components, etc., into optimized static HTML, CSS, and JavaScript files—saved by default to docs/.vitepress/dist.

2. Configure ServBay Site (Static File Service)

   The production build is a set of static files that ServBay can serve using static site functionality.

   In ServBay’s control panel, go to "Sites" and add a new configuration:

   • Name: e.g., VitePress Production Site
   • Domain: Enter a local domain for production, e.g., vitepress-prod.servbay.demo.
   • Site Type: Select Static.
   • Website Root: Enter the absolute path to your static files:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   Save and apply. ServBay will configure the web server to serve files directly from this root directory.

3. Access Your Production Site

   Now, head to your configured domain, https://vitepress-prod.servbay.demo, in your browser. You’ll see the production version of your VitePress site, complete with custom domain and automatic SSL encryption provided by ServBay.

Enabling Clean URL Mode (cleanUrls: true)

VitePress supports cleanUrls: true, which means generated links won’t contain .html extensions (e.g., /guide/ instead of /guide/index.html, or /about instead of /about.html). To make your web server handle these links correctly, further configuration is needed.

ServBay uses Caddy or Nginx. The following example is for Caddy, using try_files to search for files with or without the .html extension, or directory index.html.

1. Enable cleanUrls in VitePress

   Edit your VitePress config (docs/.vitepress/config.mts or docs/.vitepress/config.ts) and set cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... other settings
     cleanUrls: true, // Enable clean URLs
     // ... other settings
   })

   Rebuild your site with npm run docs:build.

2. Configure ServBay Site (Custom Caddy Configuration)

   In ServBay’s dashboard, go to your production site configuration (e.g., vitepress-prod.servbay.demo).

   • Click Edit.
   • Check Custom Configuration.
   • In the Caddy Configuration text area, paste/update the following. Replace servbay-vitepress-test.prod with your actual domain and update the root path:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # Replace with your actual domain, e.g., vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Enable Brotli (zstd) and Gzip compression for speed
       encode zstd gzip
   
       # Import ServBay’s default logging for easier debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Auto-manage ServBay internal SSL certificates
       tls internal
   
       # Core: try to match files
       # 1. Direct path match (e.g., /about -> /about)
       # 2. Directory index.html (e.g., /guide/ -> /guide/index.html)
       # 3. Path with .html extension (e.g., /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Set the website root directory
       # macOS: root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
       # Windows: root * C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Enable static file serving
       file_server
   }

   Save and apply your changes.

3. Browse Your Clean URL Site

   Visit your configured domain (e.g., https://vitepress-cleanurl.servbay.demo). For pages enabled with cleanUrls, you can now access them without the .html extension—for example, /about instead of /about.html.

Conclusion

Following this guide, you’ve learned to create, develop, and deploy a VitePress documentation site in the ServBay environment. ServBay greatly simplifies Node.js management and local web server setup—whether you need reverse proxy for development or static file serving for production. Plus, you get hassle-free custom domain and SSL certificate support.

Harness the power of ServBay and VitePress for a streamlined workflow to build and maintain high-quality technical documentation more efficiently.