Dark mode
ทำไมต้อง Vitepress
- ให้ความรู้สึกว่าเป็น Ecosystem เดียวกัน
Libraries ที่ใช้ vitepress ในการทำ docs ให้ให้ความรู้สึกว่าเป็น Ecosystem เดียวกับ Vite
- สร้างบนสิ่งที่คุ้นชินอยู่แล้ว
คือ vitepress สร้างบน vue, vite, markdown => ถ้าใครใช้สิ่งนี้อยู่แล้วไม่ต้องเปลี่ยนอะไรมาก
- ปรับแต่งได้เยอะ
- config.mts ที่ปรับแต่งสิ่งต่างๆได้
- ใช้ .vue ใน .md ได้
- เข้ากันได้กับ vite ทำให้ vite plugins ทั้งหมดสามารถใช้ได้
ตัวอย่าง (Examples)
Website | Description (คำอธิบาย) |
---|---|
Atomic CSS engine (เครื่องมือจัดการ CSS แบบ Atomic) | |
Syntax highlighter (ตัวเน้นสีโค้ด) | |
PWA plugin for Vite (ปลั๊กอินสร้าง PWA บน Vite) | |
Nginx configuration tool (เครื่องมือจัดการ Nginx) | |
Vite Plugin Graph Inspector (เครื่องมือตรวจสอบปลั๊กอิน Vite) | |
JavaScript tooling (เครื่องมือสำหรับ JavaScript) | |
ESLint formatting rules (กฎการจัดรูปแบบโค้ด ESLint) | |
VSCode extension development (การสร้างส่วนขยาย VSCode) | |
Vue developer tools (เครื่องมือพัฒนาสำหรับ Vue) | |
Vite-native test framework (เฟรมเวิร์กทดสอบสำหรับ Vite) |
Get Started
bash
npx vitepress init
bash
yarn vitepress init
bash
pnpm vitepress init
bash
bun vitepress init
- ลองเปิด
ดูใน 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 ต่างๆได้ ทำให้เอกสารสวยงามขึ้น
ลองดู https://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 ที่แสดงเมื่อไม่พบเนื้อหาที่ร้องขอ |
custom | Layout ที่ผู้ใช้กำหนดเองทั้งหมด ให้อิสระในการออกแบบสูงสุด |
- สร้างไฟล์ 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 ได้ตามต้องการ
},
};
- สร้าง 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 ได้
- vitepress ใช้ markdown-it เราสามารถสร้าง
markdown-it plugins แล้วนำมาใช้ได้
- หรือจะหา
markdown-it-plugins จาก npm มาใช้ก็ได้
Details
- สร้าง 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)
} }
- กำหนดที่ 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
API | Description | Example |
---|---|---|
useData() | Access site metadata | const { site } = useData() |
useRoute() | Get current route info | const route = useRoute() |
useRouter() | Programmatic navigation | const router = useRouter() |
withBase() | Add base URL to paths | withBase('/docs') |
useFrontmatter() | Access frontmatter data | const fm = useFrontmatter() |