Why Vitepress

Benefit	Description
Unified Ecosystem	ให้ระบบนิเวศที่รวมเป็นหนึ่งเดียวกับ Vite
Familiar Stack	สร้างจาก Vue, Vite และ Markdown - ไม่ต้องเรียนรู้เทคโนโลยีใหม่
Highly Customizable	- ปรับแต่งได้ผ่าน config.mts - ใช้ไฟล์ .vue ใน .md ได้ - ทำงานร่วมกับ plugin Vite ทั้งหมด

Examples

Website	Description
UnoCSS	Atomic CSS engine
Shiki	Syntax highlighter
Vite PWA	PWA plugin for Vite
Oxc	JavaScript tooling
ESLint Stylistic	ESLint formatting rules
Reactive VSCode	VSCode extension development
Vue DevTools	Vue developer tools
Vitest	Vite-native test framework

Get Started

สร้างโปรเจค Vitepress

npm

npm create vitepress@latest

pnpm

pnpm create vitepress@latest

yarn

yarn create vitepress

bun

bun create vitepress

1. ตอบคำถามในการติดตั้ง:

   • Project name: ใส่ชื่อโปรเจค
   • Select framework: Vue
   • Add TypeScript: Yes
   • Add Vitepress: Yes

2. หลังจากติดตั้งเสร็จ:

cd your-project-name

โครงสร้างโฟลเดอร์

โครงสร้างพื้นฐานของโปรเจค Vitepress:

Project

project-root/
├── .vitepress/          # การตั้งค่าหลักของ Vitepress
│   ├── config.mts       # ไฟล์ตั้งค่าหลัก
│   ├── theme/           # ธีมที่ปรับแต่ง
│   │   ├── index.ts     # ไฟล์ตั้งค่าธีม
│   │   └── style.css    # ไฟล์สไตล์ที่ปรับแต่ง
│   └── cache/           # ข้อมูลแคช
├── public/              # ไฟล์สแตติก (รูปภาพ, ฟอนต์)
├── content/             # เนื้อหาในรูปแบบ Markdown
│   ├── index.md         # หน้าหลัก
│   └── guide/           # โครงสร้างเนื้อหาตัวอย่าง
│       └── getting-started.md
├── package.json         # ไฟล์ dependencies
└── vite.config.ts       # ไฟล์ตั้งค่า Vite

การใช้ package.json

ไฟล์ package.json จะมีสคริปต์หลัก 3 ตัว:

package.json

{
  "scripts": {
    "dev": "vitepress dev",   
    "build": "vitepress build",  
    "preview": "vitepress preview" 
  }
}

Writing

Feature	Description
Markdown Extensions	รองรับไวยากรณ์ Markdown ที่ขยายเพิ่มเติม รวมถึงกลุ่มโค้ด ตัวกั้นแบบกำหนดเอง และอื่นๆ
Asset Handling	การจัดการทรัพยากรแบบสแตติกที่มีการสร้างที่ปรับให้เหมาะสมแล้ว
Frontmatter	รองรับ YAML frontmatter สำหรับข้อมูลเมตาของหน้า
Using Vue in Markdown	สามารถใช้คอมโพเนนต์ Vue โดยตรงในไฟล์ Markdown
Internationalization	รองรับ i18n ในตัวพร้อมการเปลี่ยนภาษา (กำหนดค่าใน config.mts)

Customization

config.mts

สามารถปรับแต่งธีมหลักของ Vitepress ได้โดยการกำหนดค่าในไฟล์ .vitepress/config.mts

.vitepress/config.mts

// .vitepress/config.mts
import markdownItEmoji from "markdown-it-emoji";
import { defineConfig } from "vitepress";

export default defineConfig({
  // Basic settings
  title: "My Website", // Title for SEO and browser tab
  description: "Website description", // For SEO
  base: "/docs/", // Base path for subfolder deployment
  lang: "en-US", // Default language

  // Theme configuration
  themeConfig: {
    logo: "/logo.png", // Website logo
    nav: [ // Navigation menu
      { text: "Home", link: "/" },
      { text: "Guide", link: "/guide/" },
    ],

    sidebar: [ // Sidebar menu
      {
        text: "Guide",
        items: [
          { text: "Getting Started", link: "/guide/getting-started" },
          { text: "Usage", link: "/guide/usage" },
        ],
      },
    ],

    footer: { // Footer section
      copyright: "Copyright 2024",
    },
  },

  // Markdown settings
  markdown: {
    theme: "github-dark", // Syntax highlighting theme
    lineNumbers: true, // Show line numbers
    config: (md) => {
      // Use markdown-it plugin
      md.use(markdownItEmoji);

      // Create custom plugin
      md.use(function myPlugin(md) {
        // Change ~~text~~ to <del>text</del>
        md.renderer.rules.strikethrough = (tokens, idx) => {
          return `<del>${md.utils.escapeHtml(tokens[idx].content)}</del>`;
        };
      });
    },
  },

  // Additional settings
  lastUpdated: true, // Show last updated date
  ignoreDeadLinks: true, // Don't check for dead links
  cleanUrls: true, // Use URLs without .html
});

Layout

สามารถปรับแต่งธีมหลักของ Vitepress ได้โดย:

1. สร้างไฟล์ theme/index.ts เพื่อ extend ธีมเริ่มต้น
2. ใช้คอมโพเนนต์ Vue เพื่อสร้าง Layout ที่กำหนดเอง
3. ลงทะเบียนคอมโพเนนต์ทั่วโลกผ่าน enhanceApp

index.ts

import DefaultTheme from "vitepress/theme";
import CustomLayout from "./MyLayout.vue";

export default {
  extends: DefaultTheme,
  Layout: CustomLayout,
  enhanceApp({ app }) {
    // Register global components here
  },
};

components/CustomLayout.vue

<script setup>
import DefaultTheme from "vitepress/theme";
import CustomFooter from "./CustomFooter.vue";

const { Layout } = DefaultTheme;
</script>

<template>
  <Layout>
    <!-- Add custom header section -->
    <template #top>
      <div class="custom-header">
        <h1>Welcome to My Docs</h1>
      </div>
    </template>

    <!-- Customize footer -->
    <template #footer>
      <CustomFooter />
    </template>
  </Layout>
</template>

<style scoped>
.custom-header {
  padding: 1rem;
  background: var(--vp-c-brand);
  color: white;
  text-align: center;
}
</style>

Layout Type	Slot Name	Description
doc (default)	doc-top	ด้านบนของเนื้อหาเอกสาร
	doc-bottom	ด้านล่างของเนื้อหาเอกสาร
	doc-footer-before	ก่อน footer ของเอกสาร
	doc-before	ก่อนเริ่มเนื้อหาเอกสาร
	doc-after	หลังจากจบเนื้อหาเอกสาร
	sidebar-nav-before	ก่อนเมนู sidebar
	sidebar-nav-after	หลังเมนู sidebar
	aside-top	ด้านบนของ aside section
	aside-bottom	ด้านล่างของ aside section
home	home-hero-before	ก่อน hero section
	home-hero-info	ภายในส่วนข้อมูล hero
	home-hero-image	ภายในส่วนรูปภาพ hero
	home-features-before	ก่อน features section
page	page-top	ด้านบนของหน้า
	page-bottom	ด้านล่างของหน้า
global	layout-top	ด้านบนของ layout
	nav-bar-title-before	ก่อน title ใน navbar
	nav-bar-content-after	หลัง content ใน navbar

Styling

วิธีการปรับแต่ง	คำอธิบาย
CSS Variables	ใช้ตัวแปร CSS เช่น --vp-c-brand, --vp-c-bg-alt
Component Classes	Override คลาสของ Vitepress โดยตรง เช่น .VPNav, .VPButton
Custom CSS	เขียน CSS เพิ่มเติมในไฟล์ style.css

.vitepress/theme/variables.css

:root {
  --vp-c-brand: #646cff;
  --vp-c-brand-light: #747bff;
  --vp-c-brand-dark: #535bf2;
}

.vitepress/theme/index.css

.VPNav {
  background-color: var(--vp-c-bg-alt);
}

.VPButton {
  border-radius: 6px;
}

Markdown-it Plugins

ติดตั้ง plugin ก่อนใช้งาน:

npm

npm install markdown-it-emoji markdown-it-anchor

pnpm

pnpm add markdown-it-emoji markdown-it-anchor

yarn

yarn add markdown-it-emoji markdown-it-anchor

bun

bun add markdown-it-emoji markdown-it-anchor

สามารถเพิ่ม plugin ให้กับ Markdown ได้ผ่านการกำหนดค่าใน config.mts:

.vitepress/config.mts

import markdownItEmoji from 'markdown-it-emoji'
import markdownItAnchor from 'markdown-it-anchor'

export default defineConfig({
  markdown: {
    config: (md) => {
      // ใช้ plugin ต่างๆ
      md.use(markdownItEmoji)
      md.use(markdownItAnchor, {
        level: [1, 2, 3], // เพิ่ม anchor ให้ heading level 1-3
        permalink: markdownItAnchor.permalink.ariaHidden({
          placement: 'before'
        })
      })

      // สร้าง plugin เอง
      md.use((md) => {
        md.renderer.rules.emoji = (token, idx) => {
          return `<span class="emoji">${token[idx].content}</span>`
        }
      })
    }
  }
})

Plugin	คำอธิบาย
markdown-it-emoji	เพิ่มอีโมจิ
markdown-it-anchor	เพิ่ม anchor ให้หัวข้อ
markdown-it-attrs	เพิ่ม attributes ให้ elements
markdown-it-toc-done-right	สร้างสารบัญอัตโนมัติ
markdown-it-container	สร้าง container ที่กำหนดเอง