การสร้างและใช้งานโปรเจกต์ VitePress ด้วย ServBay

VitePress คือ static site generator ยุคใหม่ที่ขับเคลื่อนโดย Vue ออกแบบมาเพื่อสร้างเว็บไซต์เอกสารที่รวดเร็ว สวยงาม และดูแลรักษาง่าย ด้วยพื้นฐานจาก Vite ทำให้ทั้งประสบการณ์การพัฒนาและประสิทธิภาพ build เหนือกว่าใคร เหมาะมากสำหรับนักพัฒนาที่ต้องสร้างเอกสารอย่างมืออาชีพสำหรับโปรเจกต์ ไลบรารี หรือผลิตภัณฑ์ของคุณ

สำหรับการพัฒนา VitePress และทดลองใช้งานแบบ local การมีสภาพแวดล้อมเว็บดีเวลอปเมนต์ที่มั่นคงและตั้งค่าง่ายจึงเป็นสิ่งที่ขาดไม่ได้ — นี่คือเหตุผลที่ ServBay ถูกออกแบบมาโดยรวม Node.js หลายเวอร์ชันและเซิร์ฟเวอร์เว็บที่ทรงพลัง (Caddy หรือ Nginx) เพื่อให้บริการโปรเจกต์ VitePress ของคุณอย่างไร้รอยต่อ

บทความนี้จะสอนวิธีสร้างและตั้งค่า VitePress ตั้งแต่เริ่มต้นในสภาพแวดล้อมที่ผสาน Node.js, reverse proxy และบริการไฟล์สถิติกับ ServBay รวมทั้งตั้งค่าโดเมนแบบ custom และ SSL ในเครื่อง

VitePress คืออะไร?

VitePress คือ static site generator (SSG) ที่พัฒนาบน Vite ดึงพลังจาก Vue 3 และความเร็วของ Vite เพื่อสร้างเว็บสถิติโดยเฉพาะเว็บเอกสารเทคนิคที่ทันสมัย

จุดเด่นหลักของ VitePress

• พัฒนาเร็วสุดขีด: ด้วย Hot Module Replacement (HMR) จาก Vite สามารถเห็นการเปลี่ยนแปลงได้แบบ real-time เพิ่มประสิทธิภาพการเขียนเอกสาร
• ขับเคลื่อนด้วย Vue: ใส่ Vue components ในไฟล์ Markdown ได้โดยตรง เพิ่มความอินเทอร์แอกทีฟและความสวยงามของเนื้อหา
• ใช้ง่าย: ตั้งค่าง่าย พร้อมใช้งาน มุ่งเน้นในการสร้างเนื้อหาเป็นหลัก
• ประสิทธิภาพสูง: ไฟล์ static ที่ build มีขนาดเล็ก โหลดเร็ว เสมือนแอปฯ single-page ด้วย client-side routing ที่มีมาให้
• เป็นมิตรต่อ SEO: โครงสร้าง HTML จากการสร้างช่วยให้ search engine จัดเก็บข้อมูลได้ง่าย และรองรับการตั้งค่า head tags แบบ custom
• Markdown ขั้นกว่า: รองรับ CommonMark และ GitHub Flavored Markdown (GFM) ทั้งหมด พร้อม syntax เพิ่มเติม

VitePress จึงเป็นตัวเลือกที่ดีเยี่ยมสำหรับการสร้างเว็บไซต์เอกสารที่มีคุณภาพและประสิทธิภาพสูง

สร้างและใช้งานโปรเจกต์ VitePress ด้วย ServBay

ServBay ให้คุณจัดการเวอร์ชัน Node.js และตั้งค่าเซิร์ฟเวอร์เว็บเพื่อให้บริการ VitePress ทั้งในโหมดพัฒนา (dev server/reverse proxy) หรือโหมดผลิต (static file)

ข้อกำหนดเบื้องต้น

ก่อนเริ่มต้นให้ตรวจสอบดังนี้:

1. ติดตั้ง ServBay: ต้องติดตั้ง ServBay ในเครื่องแล้ว หากยังไม่ติดตั้ง ดู คู่มือ ServBay.
2. ติดตั้ง Node.js package: เช็คว่าใน ServBay ได้ติดตั้งและเปิดใช้งาน Node.js เวอร์ชันที่ต้องการแล้วในหน้า “แพ็คเกจ” ของ control panel ดู การใช้งาน Node.js.

การสร้างโปรเจกต์ VitePress

1. เตรียมโฟลเดอร์โปรเจกต์

   เปิด terminal แนะนำให้สร้างไว้ใน root directory ของ ServBay เพื่อสะดวกต่อการกำหนดเว็บไซต์ในอนาคต

   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. ติดตั้ง VitePress และตั้งค่าเบื้องต้น

   ในโฟลเดอร์ servbay-vitepress-app ใช้ npm หรือ yarn ติดตั้ง VitePress เป็น dev dependency และรันคำสั่ง init

   npm add -D vitepress
   npx vitepress init

   หรือใช้ Yarn:

   yarn add -D vitepress
   yarn vitepress init

   คำสั่งเริ่มต้นจะถามข้อมูลเบื้องต้นเกี่ยวกับเว็บไซต์ เช่น ชื่อเว็บ คำอธิบาย ฯลฯ ให้กรอกตามคำแนะนำ:

    ┌  Welcome to VitePress!
    │
    ◇  Where should VitePress initialize the config?
    │  ./docs  # โฟลเดอร์เอกสารเริ่มต้น กด Enter เพื่อยืนยัน
    │
    ◇  Site title:
    │  ServBay VitePress Demo # ชื่อเว็บไซต์ เช่น ServBay VitePress Demo
    │
    ◇  Site description:
    │  A VitePress site running on ServBay # คำอธิบายเว็บไซต์
    │
    ◇  Theme:
    │  Default Theme # เลือกธีม ค่าเริ่มต้นใช้ได้เลย
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # ใช้ TypeScript ในไฟล์ config แล้วแต่ความชอบ
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # เพิ่มสคริปต์ลง package.json แนะนำเลือก Yes
    │
    └  เสร็จแล้ว! รัน npm run docs:dev เพื่อเริ่มเขียนเอกสาร

   เมื่อตั้งค่าเสร็จ VitePress จะสร้างโฟลเดอร์ docs ใน servbay-vitepress-app ซึ่งมีไฟล์ config (.vitepress) และหน้าเอกสารตัวอย่างเช่น (index.md, guide/index.md เป็นต้น นอกจากนี้จะมีการเพิ่มสคริปต์ docs:dev, docs:build ใน package.json ด้วย

แก้ไขเนื้อหาเว็บไซต์ VitePress

1. แก้ไขหน้าแรก

   หน้าแรกเริ่มต้นอยู่ใน docs/index.md เปิดแก้ไขด้วย editor ใดก็ได้ เช่นปรับเป็น:

   # Hello ServBay!
   
   ยินดีต้อนรับสู่การใช้งาน ServBay สำหรับสร้างเว็บเอกสารด้วย VitePress
   
   เว็บไซต์นี้เป็น demo VitePress ที่ให้บริการผ่าน ServBay

เข้าโหมดพัฒนา

สำหรับการพัฒนา VitePress จะใช้ dev server ซึ่งรองรับ hot reload ทันที จากนั้นใช้ความสามารถ reverse proxy ของ ServBay ในการเข้าถึงผ่านโดเมน custom พร้อมรองรับ SSL

1. รัน VitePress Dev Server

   ใน terminal ให้อยู่ที่ root directory ของโปรเจกต์ (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app) แล้วรัน server โดยระบุพอร์ต (เช่น 8585)

   npm run docs:dev -- --port 8585

   หรือใช้ Yarn:

   yarn docs:dev --port 8585

   Dev server จะรันและเปิดพอร์ตที่กำหนด (เช่น 8585) โดยปกติจะใช้ http://localhost:8585

2. กำหนดเว็บไซต์ใน ServBay (reverse proxy)

   เปิด control panel ของ ServBay ไปที่หน้า “เว็บไซต์” แล้วเพิ่มเว็บใหม่

   • ชื่อ: ระบุชื่อที่เข้าใจง่าย เช่น VitePress Dev Site
   • โดเมน: ตั้งโดเมน local สำหรับ dev เช่น vitepress-dev.servbay.demo (ควรลงท้ายด้วย .servbay.demo ตาม convention)
   • ประเภทเว็บไซต์: เลือก “Reverse Proxy”
   • IP: กำหนดเป็น 127.0.0.1
   • พอร์ต: ใส่พอร์ต dev server ที่ใช้งาน เช่น 8585

   เมื่อบันทึกและ apply การตั้งค่า ServBay จะเซ็ตเซิร์ฟเวอร์ให้รับ request ที่ https://vitepress-dev.servbay.demo และ forward ไปที่ http://127.0.0.1:8585

3. เข้าถึงเว็บไซต์ Dev

   เปิดเบราว์เซอร์ไปที่ https://vitepress-dev.servbay.demo คุณจะเห็นหน้าเว็บที่ dev server ทำงานอยู่ และด้วยการตั้งค่า ServBay จะมี SSL certificate สำหรับโดเมนนี้ให้อัตโนมัติ (ออกโดย ServBay User CA)

Build โหมด Production

เมื่อพัฒนาเสร็จและพร้อมเผยแพร่ ต้อง build ให้เป็นไฟล์ static ที่ปรับแต่งแล้ว

1. Build Production Version

   ใน terminal ที่ root directory ของโปรเจกต์ (macOS: /Applications/ServBay/www/servbay-vitepress-app, Windows: C:\ServBay\www\servbay-vitepress-app) รันคำสั่ง build:

   npm run docs:build

   หรือใช้ Yarn:

   yarn docs:build

   กระบวนการนี้จะ compile Markdown, Vue components ฯลฯ ให้ออกมาเป็นไฟล์ HTML, CSS, JS static ที่พร้อมใช้งาน ไฟล์ที่ build จะอยู่ใน docs/.vitepress/dist

2. ตั้งค่าเว็บไซต์ใน ServBay (Static File Service)

   เวอร์ชัน production ของ VitePress จะให้บริการเป็นไฟล์ static พร้อมบน ServBay

   เปิดหน้า “เว็บไซต์” ของ ServBay แล้วเพิ่มเว็บใหม่

   • ชื่อ: ตั้งชื่อเช่น VitePress Prod Site
   • โดเมน: ใช้โดเมนสำหรับ production เช่น vitepress-prod.servbay.demo
   • ประเภทเว็บไซต์: เลือก “Static”
   • root directory: ตั้ง path ไปที่โฟลเดอร์ static ที่ build เสร็จ:
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   เมื่อบันทึกและ apply การตั้งค่า ServBay จะเปิดบริการเว็บ static จากโฟลเดอร์ที่กำหนด

3. เข้าเว็บไซต์ Production

   ไปที่เบราว์เซอร์แล้วเปิด https://vitepress-prod.servbay.demo จะเห็นหน้าเว็บเวอร์ชัน production พร้อม domain และ SSL จาก ServBay

ใช้งาน Clean URL Mode (cleanUrls: true)

VitePress รองรับการตั้งค่า cleanUrls: true คือการลบนามสกุล .html ออกจากลิงก์ (เช่น /guide/ แทน /guide/index.html, /about แทน /about.html) ต้องตั้งค่า web server เพิ่มเติม

ServBay ใช้ Caddy หรือ Nginx ในที่นี้จะแสดงตัวอย่างการ config กับ Caddy โดยใช้ try_files

1. เปิดใช้งาน cleanUrls ใน VitePress

   แก้ไขไฟล์ config (docs/.vitepress/config.mts หรือ docs/.vitepress/config.ts) เพิ่ม cleanUrls:

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... other config
     cleanUrls: true, // เปิดใช้งาน clean URLs
     // ... other config
   })

   จากนั้น build ใหม่ด้วย npm run docs:build

2. ตั้งค่าเว็บไซต์ใน ServBay (Custom Caddy Config)

   เปิดหน้า "เว็บไซต์" ของ ServBay หาเว็บ production ที่สร้างไว้ (เช่น vitepress-prod.servbay.demo)

   • กดแก้ไขเว็บไซต์
   • เลือก “Custom Config”
   • ในช่อง Caddy config เพิ่มตามตัวอย่างนี้ (เปลี่ยนโดเมนและ root directory เป็นของคุณเอง):
     • macOS: /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
     • Windows: C:\ServBay\www\servbay-vitepress-app\docs\.vitepress\dist

   # เปลี่ยนโดเมน เช่น vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # เปิด Brotli (zstd) และ Gzip เพื่อโหลดเร็วขึ้น
       encode zstd gzip
   
       # import default log config ของ ServBay ไว้ debug
       import set-log vitepress-cleanurl.servbay.demo
   
       # SSL อัตโนมัติแบบ internal
       tls internal
   
       # ตั้งค่า try_files:
       # 1. หาตรง path เช่น /about -> /about
       # 2. หา index.html เช่น /guide/ -> /guide/index.html
       # 3. หาไฟล์ .html เช่น /about -> /about.html
       try_files {path} {path}/index.html {path}.html
   
       # กำหนด 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
   
       # เปิด static file server
       file_server
   }

   แล้วบันทึกและ apply การตั้งค่า

3. เปิดเข้าชมเว็บแบบ clean URL

   จากนี้ไปสามารถเข้าดูเว็บที่ https://vitepress-cleanurl.servbay.demo โดยไม่ต้องพิมพ์ .html ใน URL เช่น แทนที่จะเข้าชม about.html ให้ใช้ https://vitepress-cleanurl.servbay.demo/about ได้เลย

สรุป

จากคู่มือนี้คุณจะสามารถสร้าง พัฒนา และ deploy เว็บไซต์เอกสาร VitePress ในเครื่องด้วย ServBay ได้อย่างง่ายดาย ServBay ทำให้การจัดการสภาพแวดล้อม Node.js และการตั้งค่าเว็บเซิร์ฟเวอร์ไม่ยุ่งยาก ทั้งสำหรับ dev (reverse proxy) หรือ production (static files) พร้อมบริการ custom domain และ SSL ในเครื่องโดยอัตโนมัติ

ผสมผสานความสามารถของ ServBay และ VitePress เพื่อสร้างและดูแลเว็บไซต์เอกสารเทคนิคคุณภาพดีที่สุดได้อย่างมีประสิทธิภาพ