Create and Run a VitePress Project

What is VitePress?

VitePress is a static site generator built on Vite, designed specifically for writing documentation. Driven by Vue, VitePress boasts extremely fast build speeds and development experience. It offers a simple yet powerful API that makes creating and maintaining documentation very easy.

Major Features and Advantages of VitePress

• Fast Development Experience: VitePress uses Vite as the underlying build tool, providing lightning-fast hot updates and build speeds.
• Simple Configuration: Through simple configuration files, users can quickly set up and customize their documentation sites.
• Powerful Markdown Extensions: Supports Vue components and custom Markdown plugins, making documentation writing more flexible and powerful.
• Built-in SEO Optimization: Automatically generated site maps and optimized HTML structures enhance search engine friendliness.
• Minimal Bundle Size: With tree-shaking technology, the generated static files are very small, leading to quick loading speeds.

Using VitePress can help developers quickly build high-performance documentation websites.

Create and Run a VitePress Project Using ServBay

In this article, we'll use ServBay's Node.js environment to create and run a VitePress project. We'll utilize ServBay's 'Host' feature to set up a web server and achieve project access through reverse proxy and static file service.

Create a VitePress Project

1. Initialize the Project

   First, ensure you have installed the Node.js environment provided by ServBay. Then, initialize a new VitePress project using the following commands:

   cd /Applications/ServBay/www
   mkdir servbay-vitepress-app
   cd servbay-vitepress-app
   npm add -D vitepress
   npx vitepress init

   Follow the prompts to enter project information and choose other options as needed:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs
    │
    ◇  Site title:
    │  ServBay VitePress Demo
    │
    ◇  Site description:
    │  A ServBay VitePress Demo Site
    │
    ◇  Theme:
    │  Default Theme
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

Modify VitePress Project Content

1. Modify docs/index.md File

   Open the docs/index.md file and modify the content to display "Hello ServBay!"

   # Hello ServBay!
   
   Welcome to use ServBay to run the VitePress documentation site.

Enter Development Mode

1. Run the Development Server

   Start the development server and specify a port (e.g., 8585):

   npm run docs:dev -- --port 8585

   This will launch a local development server and expose port 8585.

2. Configure ServBay Host Reverse Proxy

   Use ServBay's 'Host' feature to access the development server through a reverse proxy. In ServBay's 'Host' settings, add a new reverse proxy:

   • Name: My first VitePress dev site
   • Domain: servbay-vitepress-test.dev
   • Host Type: Reverse Proxy
   • IP: 127.0.0.1
   • Port: 8585

   Refer to adding a Nodejs development website for detailed setup steps.

3. Access Development Mode

   Open a browser and visit https://servbay-vitepress-test.dev to view your project in real-time. Since ServBay supports custom domains and free SSL certificates, you will enjoy enhanced security.

Build Production Version

1. Build the Production Version

   Once development is complete, build the production version using the following command:

   npm run docs:build

   After building, the generated static files will be located in the docs/.vitepress/dist directory.

2. Set Up Static File Service

   Use ServBay's 'Host' feature to access the production version through static file service. In ServBay's 'Host' settings, add a new static website:

   • Name: My first VitePress production site
   • Domain: servbay-vitepress-test.prod
   • Host Type: Static
   • Website Root Directory: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

3. Access Production Mode

   Open a browser and visit https://servbay-vitepress-test.prod to view the production version of your build. With ServBay's custom domain and free SSL certificate, your site will have higher security and credibility.

Run in Clean URL mode

If your VitePress runs in clean URL mode (i.e., cleanUrls: true), please configure the following in ServBay's 'Host':

• Name: My first VitePress production site
• Domain: servbay-vitepress-test.prod
• Custom Configuration: Checked
• Caddy Config:

encode zstd gzip
import set-log servbay-vitepress-test.prod

tls internal

try_files {path} {path}/ {path}.html

root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

file_server

After saving, you can access VitePress without the .html extension. For example, https://servbay-vitepress-test.prod/path.

Following these steps, you have successfully created and run a VitePress project and used the features provided by ServBay to manage and access your project.