Creating and Running a VitePress Project with ServBay

VitePress is a modern static site generator powered by Vue, specifically designed for building fast, beautiful, and easy-to-maintain documentation websites. Built on top of Vite, it offers an exceptional development experience and impressive build performance. For developers who need to create professional documentation for projects, libraries, or products, VitePress is an outstanding choice.

When developing and testing VitePress locally, a stable and easily configurable local web development environment is crucial. That’s where ServBay comes in — it integrates multiple versions of Node.js along with robust web servers (like Caddy or Nginx), making it simple to serve your VitePress project.

This guide will walk you through leveraging ServBay's integrated environment to create, configure, and run a VitePress project from scratch, including setting up a reverse proxy for the development server as well as serving static files for the production build.

What is VitePress?

VitePress is a static site generator (SSG) based on Vite. It harnesses the power of Vue 3 and Vite's blazing-fast performance to create static sites, excelling in particular at building technical documentation.

Main Features and Advantages of VitePress

• Lightning-fast Development Experience: Thanks to Vite’s Hot Module Replacement (HMR), you’ll see content updates in the browser almost instantly, boosting your productivity.
• Vue-Powered: Directly use Vue components in Markdown files, greatly enhancing interactivity and expressiveness in your docs.
• Simple & Easy to Use: Minimal configuration, works out of the box, letting you focus on content creation.
• High Performance: Generates small, fast-loading static files, and, combined with built-in client-side routing, delivers a smooth single-page application experience.
• SEO Friendly: The generated HTML structure is optimized for search engines and supports custom head tags.
• Markdown Enhancements: Supports all CommonMark and GitHub Flavored Markdown (GFM) features, plus extra syntactic sugar.

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

Creating and Running a VitePress Project with ServBay

ServBay offers a convenient way to manage Node.js versions and configure web servers to serve your VitePress project — both for the local dev server and production static files.

Prerequisites

Before you begin, make sure you've completed the following steps:

1. ServBay Installation: ServBay should be installed on your macOS system. If it’s not installed yet, see the ServBay Installation Guide.
2. Node.js Package Installation: In ServBay, ensure the desired Node.js package version is installed and enabled. You can manage this via the "Packages" page in the ServBay control panel. Refer to Using Node.js.

Creating a VitePress Project

1. Initialize Project Directory

   Start by opening your terminal. It’s recommended to create your project folder under ServBay’s default web root /Applications/ServBay/www for easier future configuration.

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

2. Install VitePress and Initialize Configuration

   In the servbay-vitepress-app directory, install VitePress as a dev dependency and run the initialization command using npm or yarn.

   npm add -D vitepress
   npx vitepress init

   Or with Yarn:

   yarn add -D vitepress
   yarn vitepress init

   The initialization command will guide you through some basic setup steps, such as site title and description. Follow the prompts: :::no-line-numbers ┌ Welcome to VitePress! │ ◇ Where should VitePress initialize the config? │ ./docs # Default documentation directory, just hit Enter │ ◇ Site title: │ ServBay VitePress Demo # Enter your site title, e.g., ServBay VitePress Demo │ ◇ Site description: │ A VitePress site running on ServBay # Enter site description │ ◇ Theme: │ Default Theme # Choose theme, default is fine │ ◇ Use TypeScript for config and theme files? │ Yes # Use TypeScript for config, choose based on preference │ ◇ Add VitePress npm scripts to package.json? │ Yes # Add scripts to package.json, recommended │ └ Done! Now run npm run docs:dev and start writing. ::: After initialization, VitePress will create a docs subdirectory under servbay-vitepress-app, with the default config files (.vitepress) and sample pages (index.md, guide/index.md, etc.). The package.json will also be updated with entries like docs:dev and docs:build.

Editing VitePress Project Content

1. Edit the Home Page Content

   The default home page file is docs/index.md. Open this file with your favorite text editor and change its content, for example:

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

Entering Development Mode

During development, you typically use VitePress’s built-in dev server, which supports hot-reloading for quick previews. With ServBay’s reverse proxy capability, you can access this dev server through a custom domain and enjoy SSL encryption.

1. Start the VitePress Dev Server

   In the terminal, ensure you are inside /Applications/ServBay/www/servbay-vitepress-app. Start the dev server on a specified port (e.g., 8585):

   npm run docs:dev -- --port 8585

   Or with Yarn:

   yarn docs:dev --port 8585

   The dev server will listen on the specified local port (e.g., 8585). The terminal will display the local address, usually http://localhost:8585.

2. Configure ServBay Site (Reverse Proxy)

   Open the ServBay control panel and go to the "Sites" page. Click to add a new site configuration.

   • Name: Enter an easy-to-recognize name, e.g., VitePress Dev Site.
   • Domain: Enter the local domain you want to use in the browser. To comply with ServBay’s branding and avoid conflicts, it’s recommended to use the .servbay.demo suffix, e.g., vitepress-dev.servbay.demo.
   • Site Type: Select Reverse Proxy.
   • IP: Enter 127.0.0.1 (localhost).
   • Port: Enter the port specified in step 1, e.g., 8585.

   Save and apply the changes. ServBay will automatically configure the web server (such as Caddy or Nginx) to forward requests to https://vitepress-dev.servbay.demo to http://127.0.0.1:8585.

3. Access the Dev Site

   Now, in your browser, access your configured domain, https://vitepress-dev.servbay.demo. You’ll see the site provided by the VitePress dev server. Thanks to ServBay, you’ll have a custom domain and an SSL certificate signed by the ServBay User CA, enabling secure HTTPS access.

Building the Production Version

When your VitePress documentation is ready to publish, you’ll want to build an optimized static version.

1. Build the Production Version

   In the terminal at /Applications/ServBay/www/servbay-vitepress-app, run:

   npm run docs:build

   Or with Yarn:

   yarn docs:build

   This will compile and bundle your Markdown files, Vue components, etc., into optimized static HTML, CSS, and JavaScript files. By default, the generated static files will be in docs/.vitepress/dist.

2. Configure ServBay Site (Static File Service)

   The production build is a set of static files, which you can directly serve using ServBay’s static file service.

   Open the ServBay control panel and go to the "Sites" page. Click to add a new site configuration.

   • Name: Enter an easy-to-recognize name, e.g., VitePress Production Site.
   • Domain: Enter your chosen local domain for the production site, e.g., vitepress-prod.servbay.demo.
   • Site Type: Select Static.
   • Webroot: Enter the absolute path to the static files built in step 1: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist.

   Save and apply the changes. ServBay will set up the web server to serve static files directly from the specified webroot.

3. Access the Production Site

   Now, in your browser, go to https://vitepress-prod.servbay.demo. You’ll see your VitePress production website. As before, ServBay provides you with custom domains and automatic SSL encryption.

Running in Clean URL Mode (cleanUrls: true)

VitePress supports the cleanUrls: true option, which produces page links without the .html extension (e.g., /guide/ instead of /guide/index.html, or /about instead of /about.html). Web server configuration is required to properly serve these URLs.

ServBay uses Caddy or Nginx as the web server. Here’s an example Caddy config that makes use of try_files to look for appropriate files (including .html extensions or index.html under directories):

1. Enable cleanUrls in VitePress Config

   Edit your VitePress config file (docs/.vitepress/config.mts or docs/.vitepress/config.ts) and add or modify the cleanUrls option in siteConfig:

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

   Re-run npm run docs:build to build the production version.

2. Configure ServBay Site (Custom Caddy Config)

   Open the ServBay control panel and go to the "Sites" page. Locate the site for your VitePress production build (e.g., vitepress-prod.servbay.demo).

   • Click the Edit button.
   • Check the Custom Config option.
   • In the Caddy Config text area, enter or paste the following contents. Be sure to replace servbay-vitepress-test.prod with your actual domain, and /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist with your actual web root.

   # Replace with your actual domain, e.g. vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # Enable Brotli (zstd) and Gzip compression for faster loading
       encode zstd gzip
   
       # Import ServBay's default logging config for easier debugging
       import set-log vitepress-cleanurl.servbay.demo
   
       # Automatically handle ServBay internal SSL certificates
       tls internal
   
       # Core config: file lookup order
       # 1. Try the path directly (e.g., /about -> /about)
       # 2. Try index.html under the path (e.g., /guide/ -> /guide/index.html)
       # 3. Try {path}.html (e.g., /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # Set your site's web root
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # Enable static file serving
       file_server
   }

   Save and apply the changes.

3. Access the Clean URL Mode Site

   Now, visit your configured domain (e.g., https://vitepress-cleanurl.servbay.demo). For clean URLs, you can access pages without the .html extension — for example, simply access https://vitepress-cleanurl.servbay.demo/about instead of about.html.

Summary

By following this guide, you’ve learned how to create, develop, and deploy a VitePress documentation website using ServBay. ServBay simplifies Node.js environment management and local web server configuration. Whether you need a reverse proxy for development or static file serving for production, ServBay makes it easy — and automatically provides custom domains and SSL certificate support.

With the powerful combination of ServBay and VitePress, you can efficiently build and maintain high-quality technical documentation.