Skip to content

ทำไมต้อง Vitepress

  1. ให้ความรู้สึกว่าเป็น Ecosystem เดียวกัน

Libraries ที่ใช้ vitepress ในการทำ docs ให้ให้ความรู้สึกว่าเป็น Ecosystem เดียวกับ Vite

  1. สร้างบนสิ่งที่คุ้นชินอยู่แล้ว

คือ vitepress สร้างบน vue, vite, markdown => ถ้าใครใช้สิ่งนี้อยู่แล้วไม่ต้องเปลี่ยนอะไรมาก

  1. ปรับแต่งได้เยอะ
  • config.mts ที่ปรับแต่งสิ่งต่างๆได้
  • ใช้ .vue ใน .md ได้
  • เข้ากันได้กับ vite ทำให้ vite plugins ทั้งหมดสามารถใช้ได้

ตัวอย่าง (Examples)

WebsiteDescription (คำอธิบาย)
unocss.dev faviconUnoCSSAtomic CSS engine (เครื่องมือจัดการ CSS แบบ Atomic)
shiki.style faviconShikiSyntax highlighter (ตัวเน้นสีโค้ด)
vite-pwa-org.netlify.app faviconVite PWAPWA plugin for Vite (ปลั๊กอินสร้าง PWA บน Vite)
nginxui.com faviconNginx UINginx configuration tool (เครื่องมือจัดการ Nginx)
vpgi.vercel.app faviconVPGIVite Plugin Graph Inspector (เครื่องมือตรวจสอบปลั๊กอิน Vite)
oxc.rs faviconOxcJavaScript tooling (เครื่องมือสำหรับ JavaScript)
eslint.style faviconESLint StylisticESLint formatting rules (กฎการจัดรูปแบบโค้ด ESLint)
kermanx.com faviconReactive VSCodeVSCode extension development (การสร้างส่วนขยาย VSCode)
devtools-next.vuejs.org faviconVue DevToolsVue developer tools (เครื่องมือพัฒนาสำหรับ Vue)
vitest.dev faviconVitestVite-native test framework (เฟรมเวิร์กทดสอบสำหรับ Vite)

Get Started

  1. ทำตามนี้ vitepress.dev faviconhttps://vitepress.dev/guide/getting-started#setup-wizard
bash
npx vitepress init
bash
yarn vitepress init
bash
pnpm vitepress init
bash
bun vitepress init

กดไปยัง https://vitepress.dev/guide/getting-started#setup-wizard

  1. ลองเปิด

ดูใน package.json พิมพ์เช่น bun run dev แล้วก็จะเปิด http://localhost:5173

Features

Frontmatter

ใน .md ด้านบนสุดเรียกว่า frontmatter ใช้สำหรับการกำหนดค่าต่างๆ layout, sidebar, aside, outline, lastUpdated, editLink, footer, date, author, tags


layout: doc sidebar: true aside: true outline: deep lastUpdated: true editLink: true footer: true date: 2023-12-01 author: "VitePress Team" tags:

  • vitepress
  • documentation
  • vue

ใช้ Vue ใน Markdown

  • เขียน Vue Components ได้ภายใน Markdown
  • ใช้ script setup ได้โดยตรง
  • สร้าง Interactive Demos ได้ในเอกสาร

Markdown Extensions

ใช้ Markdown Extensions ต่างๆได้ ทำให้เอกสารสวยงามขึ้น

ลองดู vitepress.dev faviconhttps://vitepress.dev/guide/markdown#syntax-highlighting-in-code-blocks

Customization

config.mts

การตั้งค่าคำอธิบาย
titleกำหนดชื่อเว็บไซต์ที่จะแสดงในแท็บเบราว์เซอร์และ SEO
descriptionคำอธิบายเว็บไซต์สำหรับ SEO และแสดงในผลการค้นหา
themeConfigปรับแต่งองค์ประกอบของธีม เช่น navbar, sidebar, footer
markdownกำหนดการทำงานของ markdown parser เช่น syntax highlighting
headเพิ่ม meta tags, scripts, หรือ stylesheets ให้กับทุกหน้า
baseกำหนด URL base path สำหรับ deploy ในโฟลเดอร์ย่อย (เช่น /docs/)
outDirระบุโฟลเดอร์ปลายทางสำหรับไฟล์ที่ build แล้ว (ค่าเริ่มต้น: .vitepress/dist)
srcDirกำหนดโฟลเดอร์ต้นทางที่เก็บไฟล์ markdown (ค่าเริ่มต้น: .)
langกำหนดภาษาของเว็บไซต์ในแท็ก HTML (เช่น th-TH, en-US)
lastUpdatedเปิด/ปิดการแสดงเวลาที่อัปเดตไฟล์ล่าสุดในแต่ละหน้า
ignoreDeadLinksข้ามการตรวจสอบลิงก์ที่เสีย ป้องกันการ build ล้มเหลว
cleanUrlsใช้ URL แบบไม่มีนามสกุล .html (ต้องการการตั้งค่าเซิร์ฟเวอร์)
sitemapสร้างไฟล์ sitemap.xml อัตโนมัติสำหรับ SEO
mpaเปิดใช้โหมด Multi-Page Application แทน SPA สำหรับ SEO ที่ดีขึ้น
appearanceควบคุมการแสดงผลธีม dark/light mode และตัวเลือกสลับ
viteส่งค่า config ไปยัง Vite โดยตรง (เช่น plugins, optimizations)
vueกำหนดค่า Vue compiler options โดยตรง

Layout

ประเภท Layoutรายละเอียด
navbarแถบนำทางด้านบนของเว็บไซต์ แสดงลิงก์หลัก ปุ่มค้นหา และเมนูอื่นๆ
sidebarเมนูด้านข้างซ้าย แสดงโครงสร้างเนื้อหาและการนำทางภายในเว็บไซต์
footerส่วนท้ายของหน้าเว็บ มักแสดงลิงก์สำคัญ ลิขสิทธิ์ และข้อมูลติดต่อ
homeหน้าแรกพิเศษที่มีการออกแบบเฉพาะ มักมี hero section และส่วนแนะนำอื่นๆ
docหน้าเอกสารมาตรฐานที่แสดงเนื้อหา Markdown พร้อมกับ sidebar และ navbar
asideแถบด้านข้างขวา แสดงสารบัญของหน้าปัจจุบัน (Table of Contents)
notFoundหน้า 404 ที่แสดงเมื่อไม่พบเนื้อหาที่ร้องขอ
customLayout ที่ผู้ใช้กำหนดเองทั้งหมด ให้อิสระในการออกแบบสูงสุด
  1. สร้างไฟล์ Theme ที่ขยายจาก DefaultTheme:
ts
// .vitepress/theme/index.ts
import DefaultTheme from "vitepress/theme";
import MyLayout from "./MyLayout.vue";
import "./custom.css";

export default {
  extends: DefaultTheme,
  Layout: MyLayout,
  enhanceApp({ app, router, siteData }) {
    // ตรงนี้สามารถลงทะเบียน components, plugins หรือ
    // ทำการปรับแต่ง Vue application ได้ตามต้องการ
  },
};
  1. สร้าง Layout Component ที่ปรับแต่งได้:
vue
<!-- .vitepress/theme/MyLayout.vue -->
<script setup>
import DefaultTheme from "vitepress/theme";
import CustomFooter from "./components/CustomFooter.vue";

const { Layout } = DefaultTheme;
</script>

<template>
  <Layout>
    <template #footer>
      <CustomFooter />
    </template>
  </Layout>
</template>

สร้าง markdown plugins ได้

Details
  1. สร้าง markdown plugins

// .vitepress/plugins/emoji.ts import MarkdownIt from 'markdown-it'

export default function emoji(md: MarkdownIt) { // เปลี่ยนข้อความที่มีรูปแบบ :emoji_name: เป็น emoji icons const defaultRender = md.renderer.rules.text || ((tokens, idx) => tokens[idx].content)

md.renderer.rules.text = (tokens, idx, options, env, self) => { // แทนที่ 😄 ด้วย 😊 tokens[idx].content = tokens[idx].content.replace(/😄/g, '😊') // แทนที่ ❤️ ด้วย ❤️ tokens[idx].content = tokens[idx].content.replace(/❤️/g, '❤️') // แทนที่ 👍 ด้วย 👍 tokens[idx].content = tokens[idx].content.replace(/👍/g, '👍')

return defaultRender(tokens, idx, options, env, self)

} }

  1. กำหนดที่ config.mts
ts
// .vitepress/config.mts
import { defineConfig } from "vitepress";
import emoji from "./plugins/emoji";

export default defineConfig({
  markdown: {
    config: (md) => {
      // เพิ่ม emoji ในเอกสาร
      md.use(markdownItEmoji);

      // เพิ่ม custom containers
      md.use(markdownItContainer, "tip");
      md.use(markdownItContainer, "warning");

      // เพิ่ม task lists (checkboxes)
      md.use(markdownItTaskLists);
    },
  },
});

จากนั้นใช้ emoji ในไฟล์ markdown ได้เลย 🐶 🐺 โฮ่ง! 🐯 โฮก!

หรือใช้ containers:

ข้อแนะนำ

นี่คือข้อแนะนำที่มีประโยชน์

หรือ task lists:

  • [x] งานที่เสร็จแล้ว
  • [ ] งานที่ยังไม่เสร็จ

Runtime API

APIDescriptionExample
useData()Access site metadataconst { site } = useData()
useRoute()Get current route infoconst route = useRoute()
useRouter()Programmatic navigationconst router = useRouter()
withBase()Add base URL to pathswithBase('/docs')
useFrontmatter()Access frontmatter dataconst fm = useFrontmatter()

Last updated: