Memulai

Coba Online

Anda dapat mencoba VitePress langsung di browser Anda di StackBlitz.

Instalasi

Prasyarat

• Node.js versi 20 atau lebih tinggi.
• Terminal untuk mengakses VitePress melalui command line interface (CLI).
• Text Editor dengan dukungan sintaks Markdown.
  • VSCode direkomendasikan, bersama dengan ekstensi resmi Vue.

VitePress dapat digunakan sendiri, atau diinstal ke dalam proyek yang sudah ada. Dalam kedua kasus, Anda dapat menginstalnya dengan:

npm

$ npm add -D vitepress@next

pnpm

$ pnpm add -D vitepress@next

yarn

$ yarn add -D vitepress@next vue

bun

$ bun add -D vitepress@next

CATATAN

VitePress adalah paket ESM-only. Jangan gunakan require() untuk mengimpornya, dan pastikan package.json terdekat Anda berisi "type": "module", atau ubah ekstensi file terkait Anda seperti .vitepress/config.js menjadi .mjs/.mts. Lihat panduan troubleshooting Vite untuk detail lebih lanjut. Juga, di dalam konteks CJS async, Anda dapat menggunakan await import('vitepress') sebagai gantinya.

Setup Wizard

VitePress hadir dengan command line setup wizard yang akan membantu Anda membuat scaffold proyek dasar. Setelah instalasi, mulai wizard dengan menjalankan:

npm

$ npx vitepress init

pnpm

$ pnpm vitepress init

yarn

$ yarn vitepress init

bun

$ bun vitepress init

Anda akan disambut dengan beberapa pertanyaan sederhana:

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Where should VitePress look for your markdown files?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◇  Theme:
│  Default Theme
│
◇  Use TypeScript for config and theme files?
│  Yes
│
◇  Add VitePress npm scripts to package.json?
│  Yes
│
◇  Add a prefix for VitePress npm scripts?
│  Yes
│
◇  Prefix for VitePress npm scripts:
│  docs
│
└  Done! Now run pnpm run docs:dev and start writing.

Vue sebagai Peer Dependency

Jika Anda berniat melakukan kustomisasi yang menggunakan komponen atau API Vue, Anda juga harus menginstal vue secara eksplisit sebagai dependensi.

Struktur File

Jika Anda membangun situs VitePress standalone, Anda dapat membuat scaffold situs di direktori Anda saat ini (./). Namun, jika Anda menginstal VitePress di proyek yang sudah ada bersama kode sumber lainnya, disarankan untuk membuat scaffold situs di direktori bersarang (mis. ./docs) sehingga terpisah dari bagian proyek lainnya.

Dengan asumsi Anda memilih untuk membuat scaffold proyek VitePress di ./docs, struktur file yang dihasilkan akan terlihat seperti ini:

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

Direktori docs dianggap sebagai project root dari situs VitePress. Direktori .vitepress adalah lokasi khusus untuk file konfigurasi VitePress, cache dev server, output build, dan kode kustomisasi tema opsional.

TIP

Secara default, VitePress menyimpan cache dev server-nya di .vitepress/cache, dan output build produksi di .vitepress/dist. Jika menggunakan Git, Anda harus menambahkannya ke file .gitignore Anda. Lokasi ini juga dapat dikonfigurasi.

File Konfigurasi

File konfigurasi (.vitepress/config.js) dapat digunakan untuk menyesuaikan berbagai aspek situs VitePress Anda, dengan opsi paling dasar adalah judul dan deskripsi situs:

.vitepress/config.js

export default {
  // opsi tingkat situs
  title: 'VitePress',
  description: 'Just playing around.',

  themeConfig: {
    // opsi tingkat tema
  }
}

Anda juga dapat mengonfigurasi perilaku tema melalui opsi themeConfig. Lihat Referensi Konfigurasi untuk detail lengkap semua opsi konfigurasi.

File Sumber

File Markdown di luar direktori .vitepress dianggap sebagai file sumber.

VitePress menggunakan file-based routing: setiap file .md dikompilasi menjadi file .html yang sesuai dengan path yang sama. Misalnya, index.md akan dikompilasi menjadi index.html, dan dapat dikunjungi di path root / dari situs VitePress yang dihasilkan.

VitePress juga menyediakan kemampuan untuk menghasilkan URL yang bersih, menulis ulang path, dan menghasilkan halaman secara dinamis. Ini akan dibahas di Panduan Routing.

Menjalankan

Tool ini seharusnya juga telah menyuntikkan npm script berikut ke package.json Anda jika Anda mengizinkannya selama proses setup:

package.json

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

Script docs:dev akan memulai server dev lokal dengan hot updates instan. Jalankan dengan perintah berikut:

npm

$ npm run docs:dev

pnpm

$ pnpm run docs:dev

yarn

$ yarn docs:dev

bun

$ bun run docs:dev

Alih-alih npm script, Anda juga dapat memanggil VitePress langsung dengan:

npm

$ npx vitepress dev docs

pnpm

$ pnpm vitepress dev docs

yarn

$ yarn vitepress dev docs

bun

$ bun vitepress dev docs

Penggunaan command line lainnya didokumentasikan di Referensi CLI.

Server pengembangan seharusnya berjalan di http://localhost:5173. Kunjungi URL tersebut di browser Anda untuk melihat situs baru Anda beraksi!

Selanjutnya?

• Untuk lebih memahami bagaimana file markdown dipetakan ke HTML yang dihasilkan, lanjutkan ke Panduan Routing.

• Untuk menemukan lebih banyak tentang apa yang dapat Anda lakukan di halaman, seperti menulis konten markdown atau menggunakan Komponen Vue, lihat bagian "Writing" dari panduan. Tempat yang bagus untuk memulai adalah mempelajari tentang Ekstensi Markdown.

• Untuk menjelajahi fitur yang disediakan oleh tema dokumentasi default, lihat Referensi Konfigurasi Tema Default.

• Jika Anda ingin lebih menyesuaikan tampilan situs Anda, jelajahi cara untuk Memperluas Tema Default atau Membangun Tema Kustom.

• Setelah situs dokumentasi Anda mulai terbentuk, pastikan untuk membaca Panduan Deployment.