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

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

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

คู่มือนี้จะแนะนำวิธีใช้สภาพแวดล้อมของ ServBay ในการสร้าง ตั้งค่า และรันโปรเจกต์ VitePress ตั้งแต่เริ่มต้น พร้อมแบ่งปันแนวทางเซ็ต Reverse Proxy สำหรับเซิร์ฟเวอร์พัฒนา และบริการไฟล์สแตติกสำหรับโปรดักชัน

VitePress คืออะไร?

VitePress เป็น static site generator (SSG) ที่สร้างบน Vite นำศักยภาพของ Vue 3 และความเร็วของ Vite มาสร้างเว็บสแตติก เหมาะอย่างยิ่งกับงานเอกสารทางเทคนิค

คุณสมบัติและจุดเด่นหลักของ VitePress

• ประสบการณ์พัฒนารวดเร็วสุดขีด: ด้วย hot module replacement (HMR) ของ Vite คุณจะเห็นการอัปเดตบนเบราว์เซอร์แทบจะในทันทีที่มีการแก้ไข เพิ่มความคล่องตัวในการพัฒนา
• พลังจาก Vue: รองรับการใช้คอมโพเนนต์ Vue โดยตรงในไฟล์ Markdown ช่วยเติมเต็มความอินเทอร์แอกทีฟและความยืดหยุ่นให้กับเนื้อหา
• ใช้งานง่าย: การตั้งค่าง่ายดาย พร้อมใช้ได้ทันที และเน้นที่การสร้างสรรค์คอนเทนต์
• ประสิทธิภาพสูง: ไฟล์สแตติกที่สร้างขึ้นมีขนาดเล็ก โหลดเร็ว และผสาน client-side routing ที่ลื่นไหลดุจ SPA
• เหมาะกับ SEO: โครงสร้าง HTML ที่สร้างขึ้นเอื้อต่อ SEO และรองรับ custom head tag
• Markdown แบบจัดเต็ม: สนับสนุน CommonMark, GitHub Flavored Markdown (GFM) และมีไวยากรณ์เสริมให้ใช้งาน

VitePress ช่วยให้คุณสร้างเว็บเอกสารคุณภาพสูง ได้ผลลัพธ์ที่ยอดเยี่ยมทั้งด้านความเร็วและประสบการณ์ผู้ใช้

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

ServBay มอบวิธีง่าย ๆ ในการจัดการเวอร์ชัน Node.js และตั้งค่าเว็บเซิร์ฟเวอร์เพื่อให้บริการโปรเจกต์ VitePress ของคุณ ทั้งในโหมดพัฒนาและโปรดักชันไฟล์สแตติก

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

ก่อนเริ่มต้น กรุณาตรวจสอบให้แน่ใจว่าคุณมีสิ่งต่อไปนี้เรียบร้อยแล้ว:

1. ติดตั้ง ServBay: คุณได้ติดตั้ง ServBay สำเร็จบน macOS แล้ว หากยังไม่ได้ติดตั้ง ดู คู่มือติดตั้ง ServBay
2. ติดตั้งแพ็กเกจ Node.js: ใน ServBay โปรดตรวจสอบว่าคุณได้ติดตั้งและเปิดใช้งานแพ็กเกจ Node.js เวอร์ชันที่ต้องการแล้ว สามารถจัดการได้จากหน้า "แพ็กเกจ" ในแผงควบคุม ServBay ดู วิธีใช้ Node.js

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

1. เตรียมไดเรกทอรีโปรเจกต์

   เปิดแอป Terminal แนะนำให้สร้างโฟลเดอร์โปรเจกต์ไว้ใต้เว็บรูทเริ่มต้นของ ServBay ที่ /Applications/ServBay/www เพื่อความสะดวกในการตั้งค่าเว็บไซต์ในภายหลัง

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

2. ติดตั้ง VitePress และตั้งค่าเริ่มต้น

   ภายในไดเรกทอรีโปรเจกต์ servbay-vitepress-app ติดตั้ง VitePress เป็น dev dependency และรันคำสั่งเริ่มต้นด้วย npm หรือ yarn

   npm add -D vitepress
   npx vitepress init

   หรือใช้ Yarn:

   yarn add -D vitepress
   yarn vitepress init

   คำสั่ง 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 # เลือกธีม ค่าเริ่มต้นใช้ Default Theme ได้เลย
    │
    ◇  Use TypeScript for config and theme files?
    │  Yes # เลือกว่าจะใช้ TypeScript สำหรับไฟล์ config และธีมหรือไม่ เลือกตามความถนัด
    │
    ◇  Add VitePress npm scripts to package.json?
    │  Yes # เพิ่ม script ลงใน package.json แนะนำให้เลือก Yes
    │
    └  Done! Now run npm run docs:dev and start writing.

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

แก้ไขเนื้อหาโปรเจกต์ VitePress

1. แก้ไขเนื้อหาหน้าแรก

   หน้าแรกเริ่มต้นของ VitePress อยู่ที่ docs/index.md คุณสามารถเปิดด้วย editor ที่ชื่นชอบและแก้ไขเนื้อหา เช่น:

   # Hello ServBay!
   
   ยินดีต้อนรับสู่การใช้งาน ServBay กับเว็บไซต์เอกสาร VitePress ของคุณ
   
   ตัวอย่างเว็บไซต์ local นี้สร้างขึ้นด้วย VitePress และให้บริการด้วย ServBay

ทำงานในโหมดพัฒนา

ขณะพัฒนาเว็บไซต์ VitePress จะใช้ internal dev server ที่มี hot reload สำหรับพรีวิวเรียลไทม์ เราจะใช้ฟีเจอร์ reverse proxy ของ ServBay เพื่อเข้าถึง dev server ผ่านโดเมนของเราเอง พร้อมกับ SSL ที่ปลอดภัยจาก ServBay

1. รัน development server ของ VitePress

   ที่ terminal ภายใต้โปรเจกต์ /Applications/ServBay/www/servbay-vitepress-app ให้รันคำสั่งนี้และระบุพอร์ต (เช่น 8585)

   npm run docs:dev -- --port 8585

   หรือใช้ Yarn:

   yarn docs:dev --port 8585

   Dev server จะรันบนพอร์ตที่ระบุ (เช่น 8585) และแจ้งที่อยู่ localhost ในเทอร์มินัล เช่น http://localhost:8585

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

   เปิดแผงควบคุม ServBay ไปที่เมนู "เว็บไซต์" และกดเพิ่มเว็บไซต์ใหม่

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

   เมื่อเซฟข้อมูลแล้ว ServBay จะตั้งค่าเว็บเซิร์ฟเวอร์ (Caddy หรือ Nginx) ให้อัตโนมัติ เพื่อ forward request จาก https://vitepress-dev.servbay.demo ไปยัง http://127.0.0.1:8585

3. เข้าชม dev site

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

Build โปรเจกต์สำหรับ Production

เมื่อเอกสารพร้อม คุณต้อง build version สำหรับโปรดักชัน ซึ่งปรับแต่งมาสำหรับการนำขึ้นเซิร์ฟเวอร์

1. Build โปรดักชัน

   ที่ terminal ในไดเรกทอรีโปรเจกต์ /Applications/ServBay/www/servbay-vitepress-app รันคำสั่ง build

   npm run docs:build

   หรือใช้ Yarn:

   yarn docs:build

   ระบบจะ compile Markdown, Vue component ฯลฯ ลงเป็น HTML, CSS, JavaScript ที่ถูก optimize ไว้แล้ว ไฟล์บิ้วด์จะอยู่ใน docs/.vitepress/dist ภายใต้โปรเจกต์

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

   สำหรับ production VitePress เป็นแค่ไฟล์สแตติก ทั้งหมดสามารถเสิร์ฟผ่านฟีเจอร์ static file ของ ServBay ได้เลย

   เปิดหน้า "เว็บไซต์" บนแผงควบคุม ServBay แล้วเพิ่มเว็บไซต์ใหม่

   • ชื่อ: เช่น VitePress โปรดักชัน
   • โดเมน: เช่น vitepress-prod.servbay.demo
   • ประเภทเว็บไซต์: เลือก Static
   • ไดเรกทอรีเว็บไซต์: กรอก path ครบ เช่น /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist

   เมื่อเซฟแล้ว ServBay จะตั้งค่าเว็บเซิร์ฟเวอร์ให้เสิร์ฟไฟล์จากโฟลเดอร์นี้โดยตรง

3. เข้าชม production site

   เข้าเบราว์เซอร์เยี่ยมชม https://vitepress-prod.servbay.demo ดู production เวอร์ชันของเว็บไซต์ได้ทันที พร้อมโดเมนเฉพาะและ SSL อัตโนมัติ

เปิดใช้งานโหมด Clean URL (cleanUrls: true)

VitePress รองรับ cleanUrls: true ทำให้ลิงก์เพจที่สร้างไม่ต้องมี .html ต่อท้าย (เช่น /guide/ แทน /guide/index.html หรือ /about แทน /about.html) การตั้งค่าเว็บเซิร์ฟเวอร์จึงต้องรองรับรูปแบบนี้

ServBay ใช้ Caddy หรือ Nginx เป็นเว็บเซิร์ฟเวอร์ ตัวอย่างนี้ใช้ Caddy ด้วย directive try_files เพื่อพยายามหาตรงไฟล์ที่ถูกต้อง (รวมไฟล์ .html หรือ index.html)

1. เปิด Clean URL ในคอนฟิก VitePress

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

   // docs/.vitepress/config.mts
   import { defineConfig } from 'vitepress'
   
   export default defineConfig({
     // ... คอนฟิกอื่น ๆ
     cleanUrls: true, // เปิดใช้งาน clean URL
     // ... คอนฟิกอื่น ๆ
   })

   แล้วรัน npm run docs:build ใหม่ ให้ build ออกมาอีกครั้ง

2. ตั้งค่าเว็บไซต์ ServBay (Caddy Config แบบกำหนดเอง)

   ที่แผงควบคุม ServBay เข้าไปยังเว็บไซต์ production เช่น vitepress-prod.servbay.demo

   • กดแก้ไข
   • ติ๊กเลือก Custom Config
   • ที่กล่อง Caddy Config วางคอนฟิกตามตัวอย่างด้านล่างนี้ (เปลี่ยน servbay-vitepress-test.prod เป็นโดเมนของคุณเอง และ .../dist เป็นพาธเว็บไซต์จริง)

   # ระบุโดเมนจริง เช่น vitepress-cleanurl.servbay.demo
   vitepress-cleanurl.servbay.demo {
       # ใช้งาน Brotli (zstd) และ Gzip เพื่อเพิ่มความเร็ว
       encode zstd gzip
   
       # รวมการตั้งค่า log เริ่มต้น เพื่อความสะดวกในการดีบั๊ก
       import set-log vitepress-cleanurl.servbay.demo
   
       # ใช้ internal SSL certificate จาก ServBay
       tls internal
   
       # การตั้งค่าสำคัญ: พยายามหาไฟล์
       # 1. เข้ากับ path ตรง ๆ (เช่น /about -> /about)
       # 2. หา index.html ใต้ path (เช่น /guide/ -> /guide/index.html)
       # 3. หาไฟล์ {path}.html (เช่น /about -> /about.html)
       try_files {path} {path}/index.html {path}.html
   
       # ระบุเว็บรูท
       root * /Applications/ServBay/www/servbay-vitepress-app/docs/.vitepress/dist
   
       # เปิดบริการไฟล์สแตติก
       file_server
   }

   บันทึกและนำการตั้งค่าไปใช้

3. เยี่ยมชมเว็บไซต์ clean URL

   ตอนนี้ คุณสามารถเข้าเว็บไซต์ที่เปิดใช้ cleanUrl ได้ผ่านโดเมนของคุณ เช่น https://vitepress-cleanurl.servbay.demo โดยสามารถใช้ url ที่ไม่มี .html ต่อท้าย เช่น เข้า /about แทน /about.html

สรุป

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

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