diff --git a/.gitignore b/.gitignore index e6e95ca9e..5e7b48827 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,4 @@ pnpm-global TODOs.md *.timestamp-*.mjs .claude +.local diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index b80937139..d82c5d154 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -23,7 +23,8 @@ const localeToOgLocaleMap: Record = { es: 'es_ES', ko: 'ko_KR', fa: 'fa_IR', - ja: 'ja_JP' + ja: 'ja_JP', + id: 'id_ID' } export default defineConfig({ @@ -71,6 +72,8 @@ export default defineConfig({ return '复制代码' case 'ja': return 'コードをコピー' + case 'id': + return 'Salin kode' default: return 'Copy code' } @@ -130,7 +133,8 @@ export default defineConfig({ es: { label: 'Español', lang: 'es', dir: 'ltr' }, ko: { label: '한국어', lang: 'ko-KR', dir: 'ltr' }, fa: { label: 'فارسی', lang: 'fa-IR', dir: 'rtl' }, - ja: { label: '日本語', lang: 'ja', dir: 'ltr' } + ja: { label: '日本語', lang: 'ja', dir: 'ltr' }, + id: { label: 'Bahasa Indonesia', lang: 'id-ID', dir: 'ltr' } }, vite: { diff --git a/docs/id/guide/asset-handling.md b/docs/id/guide/asset-handling.md new file mode 100644 index 000000000..b11a8a065 --- /dev/null +++ b/docs/id/guide/asset-handling.md @@ -0,0 +1,67 @@ +--- +description: Pelajari cara mereferensikan dan menangani aset statis seperti gambar, media, dan font di VitePress. +--- + +# Penanganan Aset + +## Mereferensikan Aset Statis + +Semua file Markdown dikompilasi menjadi komponen Vue dan diproses oleh [Vite](https://vitejs.dev/guide/assets.html). Anda dapat, **dan sebaiknya**, mereferensikan aset apa pun menggunakan URL relatif: + +```md +![An image](./image.png) +``` + +Anda dapat mereferensikan aset statis di file markdown Anda, komponen `*.vue` di tema, style, dan file `.css` biasa menggunakan path publik absolut (berdasarkan project root) atau path relatif (berdasarkan file system Anda). Yang terakhir mirip dengan perilaku yang biasa Anda gunakan jika Anda pernah menggunakan Vite, Vue CLI, atau `file-loader` webpack. + +Tipe file gambar, media, dan font yang umum dideteksi dan disertakan sebagai aset secara otomatis. + +::: tip File yang ditautkan tidak diperlakukan sebagai aset +PDF atau dokumen lain yang direferensikan oleh tautan dalam file markdown tidak secara otomatis diperlakukan sebagai aset. Untuk membuat file yang ditautkan dapat diakses, Anda harus menempatkannya secara manual di dalam direktori [`public`](#direktori-public) proyek Anda. +::: + +Semua aset yang direferensikan, termasuk yang menggunakan path absolut, akan disalin ke direktori output dengan nama file yang di-hash pada build produksi. Aset yang tidak pernah direferensikan tidak akan disalin. Aset gambar yang lebih kecil dari 4kb akan di-inline base64, dan ini dapat dikonfigurasi melalui opsi konfigurasi [`vite`](../reference/site-config#vite). + +Semua referensi path **statis**, termasuk path absolut, harus didasarkan pada struktur direktori kerja Anda. + +## Direktori Public + +Terkadang Anda mungkin perlu menyediakan aset statis yang tidak direferensikan secara langsung di komponen Markdown atau tema Anda, atau Anda mungkin ingin menyajikan file tertentu dengan nama file asli. Contoh file tersebut termasuk `robots.txt`, favicon, dan ikon PWA. + +Anda dapat menempatkan file-file ini di direktori `public` di bawah [source directory](./routing#source-directory). Misalnya, jika project root Anda adalah `./docs` dan menggunakan lokasi source directory default, maka direktori public Anda akan menjadi `./docs/public`. + +Aset yang ditempatkan di `public` akan disalin ke root direktori output apa adanya. + +Perhatikan bahwa Anda harus mereferensikan file yang ditempatkan di `public` menggunakan path absolut root: misalnya, `public/icon.png` harus selalu direferensikan di kode sumber sebagai `/icon.png`. + +## Base URL + +Jika situs Anda dideploy ke URL non-root, Anda perlu mengatur opsi `base` di `.vitepress/config.js`. Misalnya, jika Anda berencana mendeploy situs Anda ke `https://foo.github.io/bar/`, maka `base` harus diatur ke `'/bar/'` (harus selalu dimulai dan diakhiri dengan garis miring). + +Semua path aset statis Anda secara otomatis diproses untuk menyesuaikan dengan nilai konfigurasi `base` yang berbeda. Misalnya, jika Anda memiliki referensi absolut ke aset di bawah `public` dalam markdown Anda: + +```md +![An image](/image-inside-public.png) +``` + +Anda **tidak** perlu memperbaruinya saat Anda mengubah nilai konfigurasi `base` dalam kasus ini. + +Namun, jika Anda menulis komponen tema yang menautkan ke aset secara dinamis, misalnya gambar yang `src`-nya didasarkan pada nilai konfigurasi tema: + +```vue + +``` + +Dalam kasus ini disarankan untuk membungkus path dengan [`withBase` helper](../reference/runtime-api#withbase) yang disediakan oleh VitePress: + +```vue + + + +``` diff --git a/docs/id/guide/cms.md b/docs/id/guide/cms.md new file mode 100644 index 000000000..d91ac1b6e --- /dev/null +++ b/docs/id/guide/cms.md @@ -0,0 +1,57 @@ +--- +outline: deep +description: Hubungkan VitePress ke headless CMS menggunakan rute dinamis dan data loader. +--- + +# Menghubungkan ke CMS + +## Alur Kerja Umum + +Menghubungkan VitePress ke CMS sebagian besar akan berkisar pada [Rute Dinamis](./routing#dynamic-routes). Pastikan Anda memahami cara kerjanya sebelum melanjutkan. + +Karena setiap CMS bekerja secara berbeda, di sini kami hanya dapat memberikan alur kerja umum yang perlu Anda adaptasi ke skenario spesifik Anda. + +1. Jika CMS Anda memerlukan otentikasi, buat file `.env` untuk menyimpan token API Anda dan muat seperti ini: + + ```js + // posts/[id].paths.js + import { loadEnv } from 'vitepress' + + const env = loadEnv('', process.cwd()) + ``` + +2. Ambil data yang diperlukan dari CMS dan format menjadi data paths yang tepat: + + ```js + export default { + async paths() { + // gunakan library klien CMS masing-masing jika diperlukan + const data = await (await fetch('https://my-cms-api', { + headers: { + // token jika diperlukan + } + })).json() + + return data.map(entry => { + return { + params: { id: entry.id, /* title, authors, date dll. */ }, + content: entry.content + } + }) + } + } + ``` + +3. Render konten di halaman: + + ```md + # {{ $params.title }} + + - oleh {{ $params.author }} pada {{ $params.date }} + + + ``` + +## Panduan Integrasi + +Jika Anda telah menulis panduan tentang mengintegrasikan VitePress dengan CMS tertentu, silakan gunakan tautan "Edit this page" di bawah ini untuk mengirimkannya di sini! diff --git a/docs/id/guide/custom-theme.md b/docs/id/guide/custom-theme.md new file mode 100644 index 000000000..c140773e5 --- /dev/null +++ b/docs/id/guide/custom-theme.md @@ -0,0 +1,220 @@ +--- +description: Buat dan gunakan tema kustom di VitePress untuk mengontrol sepenuhnya tampilan situs Anda. +--- + +# Menggunakan Tema Kustom + +## Resolusi Tema + +Anda dapat mengaktifkan tema kustom dengan membuat file `.vitepress/theme/index.js` atau `.vitepress/theme/index.ts` ("theme entry file"): + +``` +. +├─ docs # project root +│ ├─ .vitepress +│ │ ├─ theme +│ │ │ └─ index.js # theme entry +│ │ └─ config.js # config file +│ └─ index.md +└─ package.json +``` + +VitePress akan selalu menggunakan tema kustom alih-alih tema default ketika mendeteksi keberadaan theme entry file. Namun, Anda dapat [memperluas tema default](./extending-default-theme) untuk melakukan kustomisasi lanjutan di atasnya. + +## Antarmuka Tema + +Tema kustom VitePress didefinisikan sebagai objek dengan antarmuka berikut: + +```ts +interface Theme { + /** + * Komponen layout root untuk setiap halaman + * @required + */ + Layout: Component + /** + * Tingkatkan instance aplikasi Vue + * @optional + */ + enhanceApp?: (ctx: EnhanceAppContext) => Awaitable + /** + * Perluas tema lain, memanggil `enhanceApp`-nya sebelum milik kita + * @optional + */ + extends?: Theme +} + +interface EnhanceAppContext { + app: App // instance aplikasi Vue + router: Router // instance router VitePress + siteData: Ref // metadata tingkat situs +} +``` + +Theme entry file harus mengekspor tema sebagai default export-nya: + +```js [.vitepress/theme/index.js] + +// Anda dapat langsung mengimpor file Vue di theme entry +// VitePress sudah dikonfigurasi dengan @vitejs/plugin-vue. +import Layout from './Layout.vue' + +export default { + Layout, + enhanceApp({ app, router, siteData }) { + // ... + } +} +``` + +Default export adalah satu-satunya kontrak untuk tema kustom, dan hanya properti `Layout` yang diperlukan. Jadi secara teknis, tema VitePress dapat sesederhana satu komponen Vue. + +Di dalam komponen layout Anda, ia bekerja seperti aplikasi Vite + Vue 3 biasa. Perhatikan bahwa tema juga harus [SSR-compatible](./ssr-compat). + +## Membangun Layout + +Komponen layout paling dasar perlu berisi komponen [``](../reference/runtime-api#content): + +```vue [.vitepress/theme/Layout.vue] + +``` + +Layout di atas hanya merender markdown setiap halaman sebagai HTML. Peningkatan pertama yang dapat kita tambahkan adalah menangani error 404: + +```vue{1-4,9-12} + + + +``` + +Helper [`useData()`](../reference/runtime-api#usedata) memberi kita semua data runtime yang kita perlukan untuk merender layout yang berbeda secara kondisional. Salah satu data lain yang dapat kita akses adalah frontmatter halaman saat ini. Kita dapat memanfaatkan ini untuk memungkinkan pengguna akhir mengontrol layout di setiap halaman. Misalnya, pengguna dapat menunjukkan halaman harus menggunakan layout home page khusus dengan: + +```md +--- +layout: home +--- +``` + +Dan kita dapat menyesuaikan tema kita untuk menangani ini: + +```vue{3,12-14} + + + +``` + +Anda tentu saja dapat membagi layout menjadi lebih banyak komponen: + +```vue{3-5,12-15} + + + +``` + +Lihat [Referensi Runtime API](../reference/runtime-api) untuk semua yang tersedia di komponen tema. Selain itu, Anda dapat memanfaatkan [Build-Time Data Loading](./data-loading) untuk menghasilkan layout berbasis data, misalnya, halaman yang mencantumkan semua posting blog di proyek saat ini. + +## Mendistribusikan Tema Kustom + +Cara termudah untuk mendistribusikan tema kustom adalah dengan menyediakannya sebagai [template repository di GitHub](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-template-repository). + +Jika Anda ingin mendistribusikan tema sebagai paket npm, ikuti langkah-langkah berikut: + +1. Ekspor objek tema sebagai default export di entry paket Anda. + +2. Jika berlaku, ekspor definisi tipe konfigurasi tema Anda sebagai `ThemeConfig`. + +3. Jika tema Anda memerlukan penyesuaian konfigurasi VitePress, ekspor konfigurasi tersebut di bawah sub-path paket (mis. `my-theme/config`) sehingga pengguna dapat memperluasnya. + +4. Dokumentasikan opsi konfigurasi tema (baik melalui file konfigurasi maupun frontmatter). + +5. Berikan instruksi yang jelas tentang cara menggunakan tema Anda (lihat di bawah). + +## Menggunakan Tema Kustom + +Untuk menggunakan tema eksternal, impor dan ekspor ulang dari theme entry kustom: + +```js [.vitepress/theme/index.js] +import Theme from 'awesome-vitepress-theme' + +export default Theme +``` + +Jika tema perlu diperluas: + +```js [.vitepress/theme/index.js] +import Theme from 'awesome-vitepress-theme' + +export default { + extends: Theme, + enhanceApp(ctx) { + // ... + } +} +``` + +Jika tema memerlukan konfigurasi VitePress khusus, Anda juga perlu memperluasnya di konfigurasi Anda sendiri: + +```ts [.vitepress/config.ts] +import baseConfig from 'awesome-vitepress-theme/config' + +export default { + // perluas konfigurasi dasar tema (jika diperlukan) + extends: baseConfig +} +``` + +Terakhir, jika tema menyediakan tipe untuk konfigurasi temanya: + +```ts [.vitepress/config.ts] +import baseConfig from 'awesome-vitepress-theme/config' +import { defineConfigWithTheme } from 'vitepress' +import type { ThemeConfig } from 'awesome-vitepress-theme' + +export default defineConfigWithTheme({ + extends: baseConfig, + themeConfig: { + // Type adalah `ThemeConfig` + } +}) +``` diff --git a/docs/id/guide/data-loading.md b/docs/id/guide/data-loading.md new file mode 100644 index 000000000..134a045f9 --- /dev/null +++ b/docs/id/guide/data-loading.md @@ -0,0 +1,248 @@ +--- +description: Muat data apa pun pada waktu build menggunakan data loader VitePress dan impor dari halaman atau komponen. +--- + +# Build-Time Data Loading + +VitePress menyediakan fitur yang disebut **data loader** yang dapat digunakan untuk memuat data apa pun dan mengimpornya dari halaman atau komponen. Pemuatan data dieksekusi **hanya pada waktu build**: data yang dihasilkan akan diserialisasi sebagai JSON dalam bundel JavaScript akhir. + +Data loader dapat digunakan untuk mengambil data remote, atau menghasilkan metadata berdasarkan file lokal. Misalnya, Anda dapat menggunakan data loader untuk mem-parse semua halaman API lokal Anda dan secara otomatis menghasilkan indeks semua entri API. + +## Penggunaan Dasar + +File data loader harus diakhiri dengan `.data.js` atau `.data.ts`. File tersebut harus menyediakan default export berupa objek dengan metode `load()`: + +```js [example.data.js] +export default { + load() { + return { + hello: 'world' + } + } +} +``` + +Modul loader dievaluasi hanya di Node.js, sehingga Anda dapat mengimpor Node API dan dependensi npm sesuai kebutuhan. + +Anda kemudian dapat mengimpor data dari file ini di halaman `.md` dan komponen `.vue` menggunakan named export `data`: + +```vue + + +
{{ data }}
+``` + +Output: + +```json +{ + "hello": "world" +} +``` + +Anda akan melihat bahwa data loader sendiri tidak mengekspor `data`. VitePress-lah yang memanggil metode `load()` di belakang layar dan secara implisit mengekspos hasilnya melalui named export `data`. + +Ini berfungsi bahkan jika loader bersifat async: + +```js +export default { + async load() { + // ambil data remote + return (await fetch('...')).json() + } +} +``` + +## Data dari File Lokal + +Ketika Anda perlu menghasilkan data berdasarkan file lokal, Anda harus menggunakan opsi `watch` di data loader sehingga perubahan yang dibuat pada file-file ini dapat memicu hot updates. + +Opsi `watch` juga nyaman karena Anda dapat menggunakan [glob patterns](https://github.com/mrmlnc/fast-glob#pattern-syntax) untuk mencocokkan banyak file. Pattern dapat relatif terhadap file loader itu sendiri, dan fungsi `load()` akan menerima file yang cocok sebagai path absolut. + +Contoh berikut menunjukkan memuat file CSV dan mengubahnya menjadi JSON menggunakan [csv-parse](https://github.com/adaltas/node-csv/tree/master/packages/csv-parse/). Karena file ini hanya dieksekusi pada waktu build, Anda tidak akan mengirimkan parser CSV ke klien! + +```js +import fs from 'node:fs' +import { parse } from 'csv-parse/sync' + +export default { + watch: ['./data/*.csv'], + load(watchedFiles) { + // watchedFiles akan berupa array path absolut dari file yang cocok. + // hasilkan array metadata posting blog yang dapat digunakan untuk + // merender daftar di layout tema + return watchedFiles.map((file) => { + return parse(fs.readFileSync(file, 'utf-8'), { + columns: true, + skip_empty_lines: true + }) + }) + } +} +``` + +## `createContentLoader` + +Saat membangun situs yang berfokus pada konten, kita sering perlu membuat halaman "arsip" atau "indeks": halaman di mana kita mencantumkan semua entri yang tersedia dalam koleksi konten kita, misalnya posting blog atau halaman API. Kita **dapat** mengimplementasikan ini langsung dengan API data loader, tetapi karena ini adalah use case yang sangat umum, VitePress juga menyediakan helper `createContentLoader` untuk menyederhanakannya: + +```js [posts.data.js] +import { createContentLoader } from 'vitepress' + +export default createContentLoader('posts/*.md', /* options */) +``` + +Helper ini menerima glob pattern relatif terhadap [source directory](./routing#source-directory), dan mengembalikan objek data loader `{ watch, load }` yang dapat digunakan sebagai default export di file data loader. Ini juga mengimplementasikan caching berdasarkan timestamp modifikasi file untuk meningkatkan performa dev. + +Perhatikan bahwa loader hanya bekerja dengan file Markdown; file non-Markdown yang cocok akan dilewati. + +Data yang dimuat akan berupa array dengan tipe `ContentData[]`: + +```ts +interface ContentData { + // URL yang dipetakan untuk halaman. mis. /posts/hello.html (tidak termasuk base) + // iterasi secara manual atau gunakan `transform` kustom untuk menormalkan path + url: string + // data frontmatter halaman + frontmatter: Record + + // berikut hanya ada jika opsi terkait diaktifkan + // kita akan membahasnya di bawah + src: string | undefined + html: string | undefined + excerpt: string | undefined +} +``` + +Secara default, hanya `url` dan `frontmatter` yang disediakan. Ini karena data yang dimuat akan di-inline sebagai JSON di bundel klien, jadi kita perlu berhati-hati tentang ukurannya. Berikut contoh menggunakan data untuk membangun halaman indeks blog minimal: + +```vue + + + +``` + +### Opsi + +Data default mungkin tidak sesuai untuk semua kebutuhan. Anda dapat memilih untuk mentransformasi data menggunakan opsi: + +```js [posts.data.js] +import { createContentLoader } from 'vitepress' + +export default createContentLoader('posts/*.md', { + includeSrc: true, // sertakan sumber markdown mentah? + render: true, // sertakan HTML halaman penuh yang dirender? + excerpt: true, // sertakan excerpt? + transform(rawData) { + // map, sort, atau filter data mentah sesuai keinginan. + // hasil akhir adalah apa yang akan dikirim ke klien. + return rawData.sort((a, b) => { + return +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date) + }).map((page) => { + page.src // sumber markdown mentah + page.html // HTML halaman penuh yang dirender + page.excerpt // HTML excerpt yang dirender (konten di atas `---` pertama) + return {/* ... */} + }) + } +}) +``` + +Lihat bagaimana ini digunakan di [blog Vue.js](https://github.com/vuejs/blog/blob/main/.vitepress/theme/posts.data.ts). + +API `createContentLoader` juga dapat digunakan di dalam [build hooks](../reference/site-config#build-hooks): + +```js [.vitepress/config.js] +export default { + async buildEnd() { + const posts = await createContentLoader('posts/*.md').load() + // hasilkan file berdasarkan metadata posting, mis. RSS feed + } +} +``` + +**Tipe** + +```ts +interface ContentOptions { + /** + * Sertakan src? + * @default false + */ + includeSrc?: boolean + + /** + * Render src ke HTML dan sertakan dalam data? + * @default false + */ + render?: boolean + + /** + * Jika `boolean`, apakah akan mem-parse dan menyertakan excerpt? (dirender sebagai HTML) + * + * Jika `function`, kontrol bagaimana excerpt diekstrak dari konten. + * + * Jika `string`, tentukan separator kustom yang digunakan untuk mengekstrak + * excerpt. Separator default adalah `---` jika `excerpt` adalah `true`. + * + * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt + * @see https://github.com/jonschlinkert/gray-matter#optionsexcerpt_separator + * + * @default false + */ + excerpt?: + | boolean + | ((file: { data: { [key: string]: any }; content: string; excerpt?: string }, options?: any) => void) + | string + + /** + * Transformasikan data. Perhatikan data akan di-inline sebagai JSON di + * bundel klien jika diimpor dari komponen atau file markdown. + */ + transform?: (data: ContentData[]) => T | Promise +} +``` + +## Typed Data Loader + +Saat menggunakan TypeScript, Anda dapat mengetik loader dan ekspor `data` seperti ini: + +```ts +import { defineLoader } from 'vitepress' + +export interface Data { + // tipe data +} + +declare const data: Data +export { data } + +export default defineLoader({ + // opsi loader yang diperiksa tipe + watch: ['...'], + async load(): Promise { + // ... + } +}) +``` + +## Konfigurasi + +Untuk mendapatkan informasi konfigurasi di dalam loader, Anda dapat menggunakan kode seperti ini: + +```ts +import type { SiteConfig } from 'vitepress' + +const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG +``` diff --git a/docs/id/guide/deploy.md b/docs/id/guide/deploy.md new file mode 100644 index 000000000..c9654676d --- /dev/null +++ b/docs/id/guide/deploy.md @@ -0,0 +1,346 @@ +--- +description: Deploy situs VitePress Anda ke platform populer seperti Netlify, Vercel, GitHub Pages, dan lainnya. +outline: deep +--- + +# Deploy Situs VitePress Anda + +Panduan berikut didasarkan pada beberapa asumsi bersama: + +- Situs VitePress berada di dalam direktori `docs` proyek Anda. +- Anda menggunakan direktori output build default (`.vitepress/dist`). +- VitePress diinstal sebagai dependensi lokal di proyek Anda, dan Anda telah menyiapkan script berikut di `package.json` Anda: + + ```json [package.json] + { + "scripts": { + "docs:build": "vitepress build docs", + "docs:preview": "vitepress preview docs" + } + } + ``` + +## Build dan Uji Secara Lokal + +1. Jalankan perintah ini untuk membangun docs: + + ```sh + $ npm run docs:build + ``` + +2. Setelah dibangun, pratinjau secara lokal dengan menjalankan: + + ```sh + $ npm run docs:preview + ``` + + Perintah `preview` akan memulai server web statis lokal yang akan menyajikan direktori output `.vitepress/dist` di `http://localhost:4173`. Anda dapat menggunakan ini untuk memastikan semuanya terlihat baik sebelum push ke produksi. + +3. Anda dapat mengonfigurasi port server dengan meneruskan `--port` sebagai argumen. + + ```json + { + "scripts": { + "docs:preview": "vitepress preview docs --port 8080" + } + } + ``` + + Sekarang metode `docs:preview` akan meluncurkan server di `http://localhost:8080`. + +## Mengatur Public Base Path + +Secara default, kami mengasumsikan situs akan dideploy di path root domain (`/`). Jika situs Anda akan disajikan di sub-path, mis. `https://mywebsite.com/blog/`, maka Anda perlu mengatur opsi [`base`](../reference/site-config#base) ke `'/blog/'` di konfigurasi VitePress. + +**Contoh:** Jika Anda menggunakan Github (atau GitLab) Pages dan mendeploy ke `user.github.io/repo/`, maka atur `base` Anda ke `/repo/`. + +## HTTP Cache Headers + +Jika Anda memiliki kontrol atas header HTTP di server produksi Anda, Anda dapat mengonfigurasi header `cache-control` untuk mencapai performa yang lebih baik pada kunjungan berulang. + +Build produksi menggunakan nama file yang di-hash untuk aset statis (JavaScript, CSS, dan aset impor lainnya yang tidak ada di `public`). Jika Anda memeriksa pratinjau produksi menggunakan tab network devtools browser Anda, Anda akan melihat file seperti `app.4f283b18.js`. + +Hash `4f283b18` ini dihasilkan dari konten file ini. URL hash yang sama dijamin menyajikan konten file yang sama, dan jika konten berubah, URL juga berubah. Ini berarti Anda dapat dengan aman menggunakan header cache terkuat untuk file-file ini. Semua file tersebut akan ditempatkan di bawah `assets/` di direktori output, sehingga Anda dapat mengonfigurasi header berikut untuknya: + +``` +Cache-Control: max-age=31536000,immutable +``` + +::: details Contoh file `_headers` Netlify + +``` +/assets/* + cache-control: max-age=31536000 + cache-control: immutable +``` + +Catatan: file `_headers` harus ditempatkan di [direktori public](./asset-handling#direktori-public), dalam kasus kami, `docs/public/_headers`, sehingga disalin apa adanya ke direktori output. + +[Dokumentasi custom headers Netlify](https://docs.netlify.com/routing/headers/) + +::: + +::: details Contoh konfigurasi Vercel di `vercel.json` + +```json +{ + "headers": [ + { + "source": "/assets/(.*)", + "headers": [ + { + "key": "Cache-Control", + "value": "max-age=31536000, immutable" + } + ] + } + ] +} +``` + +Catatan: file `vercel.json` harus ditempatkan di root **repositori** Anda. + +[Dokumentasi Vercel tentang konfigurasi headers](https://vercel.com/docs/concepts/projects/project-configuration#headers) + +::: + +## Panduan Platform + +### Netlify / Vercel / Cloudflare Pages / AWS Amplify / Render {#generic} + +Siapkan proyek baru dan ubah pengaturan ini menggunakan dashboard Anda: + +- **Build Command:** `npm run docs:build` +- **Output Directory:** `docs/.vitepress/dist` +- **Node Version:** `20` (atau di atasnya) + +::: warning +Jangan aktifkan opsi seperti _Auto Minify_ untuk kode HTML. Ini akan menghapus komentar dari output yang memiliki arti bagi Vue. Anda mungkin melihat error hydration mismatch jika komentar-komentar tersebut dihapus. +::: + +### GitHub Pages + +1. Buat file bernama `deploy.yml` di dalam direktori `.github/workflows` proyek Anda dengan konten seperti ini: + + ```yaml [.github/workflows/deploy.yml] + # Contoh workflow untuk membangun dan mendeploy situs VitePress ke GitHub Pages + # + name: Deploy VitePress site to Pages + + on: + # Berjalan pada push yang menargetkan branch `main`. Ubah ini ke `master` jika Anda + # menggunakan branch `master` sebagai branch default. + push: + branches: [main] + + # Memungkinkan Anda menjalankan workflow ini secara manual dari tab Actions + workflow_dispatch: + + # Mengatur izin GITHUB_TOKEN untuk memungkinkan deployment ke GitHub Pages + permissions: + contents: read + pages: write + id-token: write + + # Izinkan hanya satu deployment bersamaan, melewatkan run yang antre antara run yang sedang berjalan dan antrean terbaru. + # Namun, JANGAN batalkan run yang sedang berjalan karena kami ingin mengizinkan deployment produksi ini selesai. + concurrency: + group: pages + cancel-in-progress: false + + jobs: + # Build job + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v5 + with: + fetch-depth: 0 # Tidak diperlukan jika lastUpdated tidak diaktifkan + # - uses: pnpm/action-setup@v4 # Uncomment blok ini jika Anda menggunakan pnpm + # with: + # version: 9 # Tidak diperlukan jika Anda telah mengatur "packageManager" di package.json + # - uses: oven-sh/setup-bun@v1 # Uncomment ini jika Anda menggunakan Bun + - name: Setup Node + uses: actions/setup-node@v6 + with: + node-version: 24 + cache: npm # atau pnpm / yarn + - name: Setup Pages + uses: actions/configure-pages@v4 + - name: Install dependencies + run: npm ci # atau pnpm install / yarn install / bun install + - name: Build with VitePress + run: npm run docs:build # atau pnpm docs:build / yarn docs:build / bun run docs:build + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/.vitepress/dist + + # Deployment job + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + needs: build + runs-on: ubuntu-latest + name: Deploy + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 + ``` + + ::: warning + Pastikan opsi `base` di VitePress Anda dikonfigurasi dengan benar. Lihat [Mengatur Public Base Path](#mengatur-public-base-path) untuk detail lebih lanjut. + ::: + +2. Di pengaturan repositori Anda di bawah item menu "Pages", pilih "GitHub Actions" di "Build and deployment > Source". + +3. Push perubahan Anda ke branch `main` dan tunggu workflow GitHub Actions selesai. Anda akan melihat situs Anda dideploy ke `https://.github.io/[repository]/` atau `https:///` tergantung pada pengaturan Anda. Situs Anda akan secara otomatis dideploy pada setiap push ke branch `main`. + +### GitLab Pages + +1. Atur `outDir` di konfigurasi VitePress ke `../public`. Konfigurasikan opsi `base` ke `'//'` jika Anda ingin mendeploy ke `https://.gitlab.io//`. Anda tidak memerlukan `base` jika mendeploy ke custom domain, halaman pengguna atau grup, atau memiliki pengaturan "Use unique domain" yang diaktifkan di GitLab. + +2. Buat file bernama `.gitlab-ci.yml` di root proyek Anda dengan konten di bawah ini. Ini akan membangun dan mendeploy situs Anda setiap kali Anda membuat perubahan pada konten Anda: + + ```yaml [.gitlab-ci.yml] + image: node:24 + pages: + cache: + paths: + - node_modules/ + script: + # - apk add git # Uncomment ini jika Anda menggunakan docker image kecil seperti alpine dan mengaktifkan lastUpdated + - npm install + - npm run docs:build + artifacts: + paths: + - public + only: + - main + ``` + + + +### Azure + +1. Ikuti [dokumentasi resmi](https://docs.microsoft.com/en-us/azure/static-web-apps/build-configuration). + +2. Atur nilai-nilai ini di file konfigurasi Anda (dan hapus yang tidak Anda perlukan, seperti `api_location`): + + - **`app_location`**: `/` + - **`output_location`**: `docs/.vitepress/dist` + - **`app_build_command`**: `npm run docs:build` + +### CloudRay + +Anda dapat mendeploy proyek VitePress Anda dengan [CloudRay](https://cloudray.io/) dengan mengikuti [instruksi](https://cloudray.io/articles/how-to-deploy-vitepress-site) ini. + +### Firebase + +1. Buat `firebase.json` dan `.firebaserc` di root proyek Anda: + + `firebase.json`: + + ```json [firebase.json] + { + "hosting": { + "public": "docs/.vitepress/dist", + "ignore": [] + } + } + ``` + + `.firebaserc`: + + ```json [.firebaserc] + { + "projects": { + "default": "" + } + } + ``` + +2. Setelah menjalankan `npm run docs:build`, jalankan perintah ini untuk deploy: + + ```sh + firebase deploy + ``` + +### Heroku + +1. Ikuti dokumentasi dan panduan yang diberikan di [`heroku-buildpack-static`](https://elements.heroku.com/buildpacks/heroku/heroku-buildpack-static). + +2. Buat file bernama `static.json` di root proyek Anda dengan konten di bawah ini: + + ```json [static.json] + { + "root": "docs/.vitepress/dist" + } + ``` + +### Hostinger + +Anda dapat mendeploy proyek VitePress Anda dengan [Hostinger](https://www.hostinger.com/web-apps-hosting) dengan mengikuti [instruksi](https://www.hostinger.com/support/how-to-deploy-a-nodejs-website-in-hostinger/) ini. Saat mengonfigurasi pengaturan build, pilih VitePress sebagai framework dan sesuaikan direktori root ke `./docs`. + +### Kinsta + +Anda dapat mendeploy situs VitePress Anda di [Kinsta](https://kinsta.com/static-site-hosting/) dengan mengikuti [instruksi](https://kinsta.com/docs/vitepress-static-site-example/) ini. + +### Stormkit + +Anda dapat mendeploy proyek VitePress Anda ke [Stormkit](https://www.stormkit.io) dengan mengikuti [instruksi](https://stormkit.io/blog/how-to-deploy-vitepress) ini. + +### Surge + +1. Setelah menjalankan `npm run docs:build`, jalankan perintah ini untuk deploy: + + ```sh + npx surge docs/.vitepress/dist + ``` + +### Nginx + +Berikut adalah contoh konfigurasi blok server Nginx. Setup ini mencakup kompresi gzip untuk aset berbasis teks umum, aturan untuk menyajikan file statis situs VitePress Anda dengan header caching yang tepat serta menangani `cleanUrls: true`. + +```nginx +server { + gzip on; + gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript; + + listen 80; + server_name _; + index index.html; + + location / { + # lokasi konten + root /app; + + # exact matches -> reverse clean urls -> folders -> not found + try_files $uri $uri.html $uri/ =404; + + # halaman yang tidak ada + error_page 404 /404.html; + + # folder tanpa index.html menghasilkan 403 di setup ini + error_page 403 /404.html; + + # sesuaikan header caching + # file di folder assets memiliki nama file hash + location ~* ^/assets/ { + expires 1y; + add_header Cache-Control "public, immutable"; + } + } +} +``` + +Konfigurasi ini mengasumsikan bahwa situs VitePress yang telah dibangun terletak di direktori `/app` di server Anda. Sesuaikan directive `root` jika file situs Anda berada di tempat lain. + +::: warning Jangan default ke index.html +Resolusi try_files tidak boleh default ke index.html seperti di aplikasi Vue lainnya. Ini akan menghasilkan state halaman yang tidak valid. +::: + +Informasi lebih lanjut dapat ditemukan di [dokumentasi resmi nginx](https://nginx.org/en/docs/), di isu-isu ini [#2837](https://github.com/vuejs/vitepress/discussions/2837), [#3235](https://github.com/vuejs/vitepress/issues/3235) serta di [blog post](https://blog.mehdi.cc/articles/vitepress-cleanurls-on-nginx-environment#readings) oleh Mehdi Merah. diff --git a/docs/id/guide/extending-default-theme.md b/docs/id/guide/extending-default-theme.md new file mode 100644 index 000000000..c1c2c6044 --- /dev/null +++ b/docs/id/guide/extending-default-theme.md @@ -0,0 +1,334 @@ +--- +description: Kustomisasi dan perluas tema default VitePress dengan CSS kustom, komponen, layout, dan slot. +outline: deep +--- + +# Memperluas Tema Default + +Tema default VitePress dioptimalkan untuk dokumentasi, dan dapat dikustomisasi. Lihat [Ikhtisar Konfigurasi Tema Default](../reference/default-theme-config) untuk daftar opsi yang komprehensif. + +Namun, ada beberapa kasus di mana konfigurasi saja tidak cukup. Misalnya: + +1. Anda perlu mengubah styling CSS; +2. Anda perlu memodifikasi instance aplikasi Vue, misalnya untuk mendaftarkan komponen global; +3. Anda perlu menyuntikkan konten kustom ke dalam tema melalui layout slot. + +Kustomisasi lanjutan ini akan memerlukan penggunaan tema kustom yang "memperluas" tema default. + +::: tip +Sebelum melanjutkan, pastikan untuk membaca [Menggunakan Tema Kustom](./custom-theme) terlebih dahulu untuk memahami cara kerja tema kustom. +::: + +## Menyesuaikan CSS + +CSS tema default dapat dikustomisasi dengan menimpa CSS variable tingkat root: + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' +import './custom.css' + +export default DefaultTheme +``` + +```css +/* .vitepress/theme/custom.css */ +:root { + --vp-c-brand-1: #646cff; + --vp-c-brand-2: #747bff; +} +``` + +Lihat [CSS variable tema default](https://github.com/vuejs/vitepress/blob/main/src/client/theme-default/styles/vars.css) yang dapat ditimpa. + +## Menggunakan Font yang Berbeda + +VitePress menggunakan [Inter](https://rsms.me/inter/) sebagai font default, dan akan menyertakan font tersebut dalam output build. Font juga otomatis di-preload di produksi. Namun, ini mungkin tidak diinginkan jika Anda ingin menggunakan font utama yang berbeda. + +Untuk menghindari menyertakan Inter dalam output build, impor tema dari `vitepress/theme-without-fonts` sebagai gantinya: + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme-without-fonts' +import './my-fonts.css' + +export default DefaultTheme +``` + +```css +/* .vitepress/theme/my-fonts.css */ +:root { + --vp-font-family-base: /* font teks normal */ + --vp-font-family-mono: /* font kode */ +} +``` + +::: warning +Jika Anda menggunakan komponen opsional seperti komponen [Team Page](../reference/default-theme-team-page), pastikan untuk juga mengimpornya dari `vitepress/theme-without-fonts`! +::: + +Jika font Anda adalah file lokal yang direferensikan melalui `@font-face`, itu akan diproses sebagai aset dan disertakan di bawah `.vitepress/dist/assets` dengan nama file hash. Untuk mem-preload file ini, gunakan build hook [transformHead](../reference/site-config#transformhead): + +```js [.vitepress/config.js] +export default { + transformHead({ assets }) { + // sesuaikan regex untuk mencocokkan font Anda + const myFontFile = assets.find(file => /font-name\.[\w-]+\.woff2/.test(file)) + if (myFontFile) { + return [ + [ + 'link', + { + rel: 'preload', + href: myFontFile, + as: 'font', + type: 'font/woff2', + crossorigin: '' + } + ] + ] + } + } +} +``` + +## Mendaftarkan Komponen Global + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' + +/** @type {import('vitepress').Theme} */ +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + // daftarkan komponen global kustom Anda + app.component('MyGlobalComponent' /* ... */) + } +} +``` + +Jika Anda menggunakan TypeScript: +```ts [.vitepress/theme/index.ts] +import type { Theme } from 'vitepress' +import DefaultTheme from 'vitepress/theme' + +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + // daftarkan komponen global kustom Anda + app.component('MyGlobalComponent' /* ... */) + } +} satisfies Theme +``` + +Karena kita menggunakan Vite, Anda juga dapat memanfaatkan [fitur glob import Vite](https://vitejs.dev/guide/features.html#glob-import) untuk mendaftarkan direktori komponen secara otomatis. + +## Layout Slots + +Komponen `` tema default memiliki beberapa slot yang dapat digunakan untuk menyuntikkan konten di lokasi tertentu halaman. Berikut contoh menyuntikkan komponen ke before outline: + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' +import MyLayout from './MyLayout.vue' + +export default { + extends: DefaultTheme, + // timpa Layout dengan komponen wrapper yang + // menyuntikkan slot + Layout: MyLayout +} +``` + +```vue [.vitepress/theme/MyLayout.vue] + + + +``` + +Atau Anda dapat menggunakan render function juga. + +```js [.vitepress/theme/index.js] +import { h } from 'vue' +import DefaultTheme from 'vitepress/theme' +import MyComponent from './MyComponent.vue' + +export default { + extends: DefaultTheme, + Layout() { + return h(DefaultTheme.Layout, null, { + 'aside-outline-before': () => h(MyComponent) + }) + } +} +``` + +Daftar lengkap slot yang tersedia di layout tema default: + +- Ketika `layout: 'doc'` (default) diaktifkan melalui frontmatter: + - `doc-top` + - `doc-bottom` + - `doc-footer-before` + - `doc-before` + - `doc-after` + - `sidebar-nav-before` + - `sidebar-nav-after` + - `aside-top` + - `aside-bottom` + - `aside-outline-before` + - `aside-outline-after` + - `aside-ads-before` + - `aside-ads-after` +- Ketika `layout: 'home'` diaktifkan melalui frontmatter: + - `home-hero-before` + - `home-hero-info-before` + - `home-hero-info` + - `home-hero-info-after` + - `home-hero-actions-before-actions` + - `home-hero-actions-after` + - `home-hero-image` + - `home-hero-after` + - `home-features-before` + - `home-features-after` +- Ketika `layout: 'page'` diaktifkan melalui frontmatter: + - `page-top` + - `page-bottom` +- Pada halaman not found (404): + - `not-found` +- Selalu: + - `layout-top` + - `layout-bottom` + - `nav-bar-title-before` + - `nav-bar-title-after` + - `nav-bar-content-before` + - `nav-bar-content-after` + - `nav-screen-content-before` + - `nav-screen-content-after` + +## Menggunakan View Transitions API + +### Pada Toggle Appearance + +Anda dapat memperluas tema default untuk menyediakan transisi kustom saat mode warna di-toggle. Contoh: + +```vue [.vitepress/theme/Layout.vue] + + + + + +``` + +Hasil (**peringatan!**: warna berkedip, gerakan tiba-tiba, cahaya terang): + +
+Demo + +![Appearance Toggle Transition Demo](/appearance-toggle-transition.webp) + +
+ +Lihat [Chrome Docs](https://developer.chrome.com/docs/web-platform/view-transitions/) untuk detail lebih lanjut tentang view transitions. + +### Pada Perubahan Rute + +Segera hadir. + +## Menimpa Komponen Internal + +Anda dapat menggunakan [alias Vite](https://vitejs.dev/config/shared-options.html#resolve-alias) untuk mengganti komponen tema default dengan yang kustom: + +```ts +import { fileURLToPath, URL } from 'node:url' +import { defineConfig } from 'vitepress' + +export default defineConfig({ + vite: { + resolve: { + alias: [ + { + find: /^.*\/VPNavBar\.vue$/, + replacement: fileURLToPath( + new URL('./theme/components/CustomNavBar.vue', import.meta.url) + ) + } + ] + } + } +}) +``` + +Untuk mengetahui nama pasti komponen, lihat [kode sumber kami](https://github.com/vuejs/vitepress/tree/main/src/client/theme-default/components). Karena komponen bersifat internal, ada kemungkinan kecil namanya diperbarui di antara rilis minor. diff --git a/docs/id/guide/frontmatter.md b/docs/id/guide/frontmatter.md new file mode 100644 index 000000000..69615b7b1 --- /dev/null +++ b/docs/id/guide/frontmatter.md @@ -0,0 +1,52 @@ +--- +description: Pelajari cara menggunakan YAML frontmatter di file Markdown VitePress untuk mengontrol metadata dan perilaku tingkat halaman. +--- + +# Frontmatter + +## Penggunaan + +VitePress mendukung YAML frontmatter di semua file Markdown, mem-parsing-nya dengan [gray-matter](https://github.com/jonschlinkert/gray-matter). Frontmatter harus berada di bagian atas file Markdown (sebelum elemen apa pun termasuk tag ` + + +``` + +## Dukungan RTL (Eksperimental) + +Untuk dukungan RTL, tentukan `dir: 'rtl'` di konfigurasi dan gunakan beberapa plugin RTLCSS PostCSS seperti , atau . Anda perlu mengonfigurasi plugin PostCSS Anda untuk menggunakan `:where([dir="ltr"])` dan `:where([dir="rtl"])` sebagai prefix untuk mencegah masalah CSS specificity. diff --git a/docs/id/guide/markdown.md b/docs/id/guide/markdown.md new file mode 100644 index 000000000..3af9a9f06 --- /dev/null +++ b/docs/id/guide/markdown.md @@ -0,0 +1,1039 @@ +--- +description: Ekstensi Markdown bawaan VitePress termasuk custom container, blok kode dengan syntax highlighting, line highlighting, code group, dan lainnya. +--- + +# Ekstensi Markdown + +VitePress hadir dengan ekstensi Markdown bawaan. + +## Header Anchors + +Header secara otomatis mendapatkan tautan anchor. Rendering anchor dapat dikonfigurasi menggunakan opsi `markdown.anchor`. + +### Custom anchors + +Untuk menentukan tag anchor kustom untuk heading alih-alih menggunakan yang dihasilkan otomatis, tambahkan suffix ke heading: + +``` +# Menggunakan custom anchors {#my-anchor} +``` + +Dengan ini, Anda dapat menautkan ke heading sebagai `#my-anchor` alih-alih default `#menggunakan-custom-anchors`. + +## Tautan + +Tautan internal dan eksternal mendapatkan perlakuan khusus. + +### Tautan Internal + +Tautan internal dikonversi menjadi router link untuk navigasi SPA. Selain itu, setiap `index.md` yang terdapat di setiap sub-direktori akan secara otomatis dikonversi menjadi `index.html`, dengan URL terkait `/`. + +Misalnya, dengan struktur direktori berikut: + +``` +. +├─ index.md +├─ foo +│ ├─ index.md +│ ├─ one.md +│ └─ two.md +└─ bar + ├─ index.md + ├─ three.md + └─ four.md +``` + +Dan dengan asumsi Anda berada di `foo/one.md`: + +```md +[Home](/) +[foo](/foo/) +[foo heading](./#heading) +[bar - three](../bar/three) +[bar - three](../bar/three.md) +[bar - four](../bar/four.html) +``` + +### Page Suffix + +Halaman dan tautan internal dihasilkan dengan suffix `.html` secara default. + +### Tautan Eksternal + +Tautan keluar secara otomatis mendapatkan `target="_blank" rel="noreferrer"`: + +- [vuejs.org](https://vuejs.org) +- [VitePress on GitHub](https://github.com/vuejs/vitepress) + +## Frontmatter + +[YAML frontmatter](https://jekyllrb.com/docs/front-matter/) didukung secara bawaan: + +```yaml +--- +title: Blogging Like a Hacker +lang: en-US +--- +``` + +Data ini akan tersedia untuk halaman lainnya, bersama dengan semua komponen kustom dan tema. + +Untuk detail lebih lanjut, lihat [Frontmatter](../reference/frontmatter-config). + +## Tabel Gaya GitHub + +**Input** + +```md +| Tables | Are | Cool | +| ------------- | :-----------: | ----: | +| col 3 is | right-aligned | $1600 | +| col 2 is | centered | $12 | +| zebra stripes | are neat | $1 | +``` + +**Output** + +| Tables | Are | Cool | +| ------------- | :-----------: | -----: | +| col 3 is | right-aligned | \$1600 | +| col 2 is | centered | \$12 | +| zebra stripes | are neat | \$1 | + +## Emoji :tada: + +**Input** + +``` +:tada: :100: +``` + +**Output** + +:tada: :100: + +[Daftar semua emoji](https://github.com/markdown-it/markdown-it-emoji/blob/master/lib/data/full.mjs) tersedia. + +## Daftar Isi + +**Input** + +``` +[[toc]] +``` + +**Output** + +[[toc]] + +Rendering TOC dapat dikonfigurasi menggunakan opsi `markdown.toc`. + +## Custom Container + +Custom container dapat didefinisikan berdasarkan tipe, judul, dan kontennya. + +### Judul Default + +**Input** + +```md +::: info +This is an info box. +::: + +::: tip +This is a tip. +::: + +::: warning +This is a warning. +::: + +::: danger +This is a dangerous warning. +::: + +::: details +This is a details block. +::: +``` + +**Output** + +::: info +This is an info box. +::: + +::: tip +This is a tip. +::: + +::: warning +This is a warning. +::: + +::: danger +This is a dangerous warning. +::: + +::: details +This is a details block. +::: + +### Judul Kustom + +Anda dapat mengatur judul kustom dengan menambahkan teks tepat setelah "tipe" container. + +**Input** + +````md +::: danger STOP +Danger zone, do not proceed +::: + +::: details Click me to toggle the code +```js +console.log('Hello, VitePress!') +``` +::: +```` + +**Output** + +::: danger STOP +Danger zone, do not proceed +::: + +::: details Click me to toggle the code +```js +console.log('Hello, VitePress!') +``` +::: + +Selain itu, Anda dapat mengatur judul kustom secara global dengan menambahkan konten berikut di konfigurasi situs, berguna jika tidak menulis dalam bahasa Inggris: + +```ts +// config.ts +export default defineConfig({ + // ... + markdown: { + container: { + tipLabel: '提示', + warningLabel: '警告', + dangerLabel: '危险', + infoLabel: '信息', + detailsLabel: '详细信息' + } + } + // ... +}) +``` + +### Atribut Tambahan + +Anda dapat menambahkan atribut tambahan ke custom container. Kami menggunakan [markdown-it-attrs](https://github.com/arve0/markdown-it-attrs) untuk fitur ini, dan ini didukung di hampir semua elemen markdown. Misalnya, Anda dapat mengatur atribut `open` untuk membuat details block terbuka secara default: + +**Input** + +````md +::: details Click me to toggle the code {open} +```js +console.log('Hello, VitePress!') +``` +::: +```` + +**Output** + +::: details Click me to toggle the code {open} +```js +console.log('Hello, VitePress!') +``` +::: + +### `raw` + +Ini adalah container khusus yang dapat digunakan untuk mencegah konflik style dan router dengan VitePress. Ini sangat berguna ketika Anda mendokumentasikan library komponen. Anda mungkin juga ingin memeriksa [whyframe](https://whyframe.dev/docs/integrations/vitepress) untuk isolasi yang lebih baik. + +**Sintaks** + +```md +::: raw +Wraps in a `
` +::: +``` + +Kelas `vp-raw` juga dapat digunakan langsung pada elemen. Isolasi style saat ini bersifat opt-in: + +- Instal `postcss` dengan package manager pilihan Anda: + + ```sh + $ npm add -D postcss + ``` + +- Buat file bernama `docs/postcss.config.mjs` dan tambahkan ini ke dalamnya: + + ```js + import { postcssIsolateStyles } from 'vitepress' + + export default { + plugins: [postcssIsolateStyles()] + } + ``` + + Anda dapat meneruskan opsinya seperti ini: + + ```js + postcssIsolateStyles({ + includeFiles: [/custom\.css/] // default ke [/vp-doc\.css/, /base\.css/] + }) + ``` + +## GitHub-flavored Alerts + +VitePress juga mendukung [GitHub-flavored alerts](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) untuk dirender sebagai callout. Mereka akan dirender sama seperti [custom container](#custom-container). + +```md +> [!NOTE] +> Menyoroti informasi yang harus diperhatikan pengguna, bahkan saat membaca sekilas. + +> [!TIP] +> Informasi opsional untuk membantu pengguna lebih sukses. + +> [!IMPORTANT] +> Informasi penting yang diperlukan pengguna untuk berhasil. + +> [!WARNING] +> Konten penting yang menuntut perhatian pengguna segera karena potensi risiko. + +> [!CAUTION] +> Konsekuensi negatif potensial dari suatu tindakan. +``` + +> [!NOTE] +> Menyoroti informasi yang harus diperhatikan pengguna, bahkan saat membaca sekilas. + +> [!TIP] +> Informasi opsional untuk membantu pengguna lebih sukses. + +> [!IMPORTANT] +> Informasi penting yang diperlukan pengguna untuk berhasil. + +> [!WARNING] +> Konten penting yang menuntut perhatian pengguna segera karena potensi risiko. + +> [!CAUTION] +> Konsekuensi negatif potensial dari suatu tindakan. + +## Syntax Highlighting di Blok Kode + +VitePress menggunakan [Shiki](https://github.com/shikijs/shiki) untuk menyorot sintaks bahasa di blok kode Markdown, menggunakan teks berwarna. Shiki mendukung berbagai bahasa pemrograman. Yang perlu Anda lakukan adalah menambahkan alias bahasa yang valid ke awal backtick untuk blok kode: + +**Input** + +```` +```js +export default { + name: 'MyComponent', + // ... +} +``` +```` + +```` +```html +
    +
  • + {{ todo.text }} +
    • +
+``` +```` + +**Output** + +```js +export default { + name: 'MyComponent' + // ... +} +``` + +```html +
    +
  • + {{ todo.text }} +
    • +
+``` + +[Daftar bahasa yang valid](https://shiki.style/languages) tersedia di repositori Shiki. + +Anda juga dapat menyesuaikan tema syntax highlight, mengonfigurasi alias bahasa, dan mengatur label bahasa kustom di app config. Lihat [opsi `markdown`](../reference/site-config#markdown) untuk detail lebih lanjut. + +## Line Highlighting di Blok Kode + +**Input** + +```` +```js{4} +export default { + data () { + return { + msg: 'Highlighted!' + } + } +} +``` +```` + +**Output** + +```js{4} +export default { + data () { + return { + msg: 'Highlighted!' + } + } +} +``` + +Selain satu baris, Anda juga dapat menentukan beberapa baris tunggal, rentang, atau keduanya: + +- Rentang baris: misalnya `{5-8}`, `{3-10}`, `{10-17}` +- Beberapa baris tunggal: misalnya `{4,7,9}` +- Rentang baris dan baris tunggal: misalnya `{4,7-13,16,23-27,40}` + +**Input** + +```` +```js{1,4,6-8} +export default { // Highlighted + data () { + return { + msg: `Highlighted! + This line isn't highlighted, + but this and the next 2 are.`, + motd: 'VitePress is awesome', + lorem: 'ipsum' + } + } +} +``` +```` + +**Output** + +```js{1,4,6-8} +export default { // Highlighted + data () { + return { + msg: `Highlighted! + This line isn't highlighted, + but this and the next 2 are.`, + motd: 'VitePress is awesome', + lorem: 'ipsum', + } + } +} +``` + +Alternatifnya, dimungkinkan untuk menyorot langsung di baris dengan menggunakan komentar `// [!code highlight]`. + +**Input** + +```` +```js +export default { + data () { + return { + msg: 'Highlighted!' // [!!code highlight] + } + } +} +``` +```` + +**Output** + +```js +export default { + data() { + return { + msg: 'Highlighted!' // [!code highlight] + } + } +} +``` + +## Focus di Blok Kode + +Menambahkan komentar `// [!code focus]` pada sebuah baris akan memfokuskannya dan memburamkan bagian kode lainnya. + +Selain itu, Anda dapat menentukan jumlah baris untuk difokuskan menggunakan `// [!code focus:]`. + +**Input** + +```` +```js +export default { + data () { + return { + msg: 'Focused!' // [!!code focus] + } + } +} +``` +```` + +**Output** + +```js +export default { + data() { + return { + msg: 'Focused!' // [!code focus] + } + } +} +``` + +## Colored Diffs di Blok Kode + +Menambahkan komentar `// [!code --]` atau `// [!code ++]` pada sebuah baris akan membuat diff dari baris tersebut, sambil mempertahankan warna dari blok kode. + +**Input** + +```` +```js +export default { + data () { + return { + msg: 'Removed' // [!!code --] + msg: 'Added' // [!!code ++] + } + } +} +``` +```` + +**Output** + +```js +export default { + data () { + return { + msg: 'Removed' // [!code --] + msg: 'Added' // [!code ++] + } + } +} +``` + +## Errors dan Warnings di Blok Kode + +Menambahkan komentar `// [!code warning]` atau `// [!code error]` pada sebuah baris akan mewarnainya sesuai. + +**Input** + +```` +```js +export default { + data () { + return { + msg: 'Error', // [!!code error] + msg: 'Warning' // [!!code warning] + } + } +} +``` +```` + +**Output** + +```js +export default { + data() { + return { + msg: 'Error', // [!code error] + msg: 'Warning' // [!code warning] + } + } +} +``` + +## Nomor Baris + +Anda dapat mengaktifkan nomor baris untuk setiap blok kode melalui konfigurasi: + +```js +export default { + markdown: { + lineNumbers: true + } +} +``` + +Lihat [opsi `markdown`](../reference/site-config#markdown) untuk detail lebih lanjut. + +Anda dapat menambahkan tanda `:line-numbers` / `:no-line-numbers` di fenced code block Anda untuk menimpa nilai yang diatur dalam konfigurasi. + +Anda juga dapat menyesuaikan nomor baris awal dengan menambahkan `=` setelah `:line-numbers`. Misalnya, `:line-numbers=2` berarti nomor baris di blok kode akan dimulai dari `2`. + +**Input** + +````md +```ts {1} +// line-numbers is disabled by default +const line2 = 'This is line 2' +const line3 = 'This is line 3' +``` + +```ts:line-numbers {1} +// line-numbers is enabled +const line2 = 'This is line 2' +const line3 = 'This is line 3' +``` + +```ts:line-numbers=2 {1} +// line-numbers is enabled and start from 2 +const line3 = 'This is line 3' +const line4 = 'This is line 4' +``` +```` + +**Output** + +```ts {1} +// line-numbers is disabled by default +const line2 = 'This is line 2' +const line3 = 'This is line 3' +``` + +```ts:line-numbers {1} +// line-numbers is enabled +const line2 = 'This is line 2' +const line3 = 'This is line 3' +``` + +```ts:line-numbers=2 {1} +// line-numbers is enabled and start from 2 +const line3 = 'This is line 3' +const line4 = 'This is line 4' +``` + +## Import Code Snippets + +Anda dapat mengimpor potongan kode dari file yang ada melalui sintaks berikut: + +```md +<<< @/filepath +``` + +Ini juga mendukung [line highlighting](#line-highlighting-di-blok-kode): + +```md +<<< @/filepath{highlightLines} +``` + +**Input** + +```md +<<< @/snippets/snippet.js{2} +``` + +**File kode** + +<<< @/snippets/snippet.js + +**Output** + +<<< @/snippets/snippet.js{2} + +::: tip +Nilai `@` sesuai dengan source root. Secara default, ini adalah project root VitePress, kecuali `srcDir` dikonfigurasi. Alternatifnya, Anda juga dapat mengimpor dari path relatif: + +```md +<<< ../snippets/snippet.js +``` + +::: + +Anda juga dapat menggunakan [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) untuk hanya menyertakan bagian yang sesuai dari file kode. Anda dapat memberikan nama region kustom setelah `#` mengikuti filepath: + +**Input** + +```md +<<< @/snippets/snippet-with-region.js#snippet{1} +``` + +**File kode** + +<<< @/snippets/snippet-with-region.js + +**Output** + +<<< @/snippets/snippet-with-region.js#snippet{1} + +Anda juga dapat menentukan bahasa di dalam kurung kurawal (`{}`) seperti ini: + +```md +<<< @/snippets/snippet.cs{c#} + + + +<<< @/snippets/snippet.cs{1,2,4-6 c#} + + + +<<< @/snippets/snippet.cs{1,2,4-6 c#:line-numbers} +``` + +Ini berguna jika bahasa sumber tidak dapat disimpulkan dari ekstensi file Anda. + +## Code Groups + +Anda dapat mengelompokkan beberapa blok kode seperti ini: + +**Input** + +````md +::: code-group + +```js [config.js] +/** + * @type {import('vitepress').UserConfig} + */ +const config = { + // ... +} + +export default config +``` + +```ts [config.ts] +import type { UserConfig } from 'vitepress' + +const config: UserConfig = { + // ... +} + +export default config +``` + +::: +```` + +**Output** + +::: code-group + +```js [config.js] +/** + * @type {import('vitepress').UserConfig} + */ +const config = { + // ... +} + +export default config +``` + +```ts [config.ts] +import type { UserConfig } from 'vitepress' + +const config: UserConfig = { + // ... +} + +export default config +``` + +::: + +Anda juga dapat [mengimpor potongan kode](#import-code-snippets) di code group: + +**Input** + +```md +::: code-group + + + +<<< @/snippets/snippet.js + + + +<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region] + +::: +``` + +**Output** + +::: code-group + +<<< @/snippets/snippet.js + +<<< @/snippets/snippet-with-region.js#snippet{1,2 ts:line-numbers} [snippet with region] + +::: + +## Markdown File Inclusion + +Anda dapat menyertakan file markdown di dalam file markdown lain, bahkan bersarang. + +::: tip +Anda juga dapat menambahkan prefix path markdown dengan `@`, dan itu akan bertindak sebagai source root. Secara default, source root adalah project root VitePress, kecuali `srcDir` dikonfigurasi. +::: + +Misalnya, Anda dapat menyertakan file markdown relatif menggunakan ini: + +**Input** + +```md +# Docs + +## Basics + + +``` + +**File bagian** (`parts/basics.md`) + +```md +Some getting started stuff. + +### Configuration + +Can be created using `.foorc.json`. +``` + +**Kode setara** + +```md +# Docs + +## Basics + +Some getting started stuff. + +### Configuration + +Can be created using `.foorc.json`. +``` + +Ini juga mendukung pemilihan rentang baris: + +**Input** + +```md:line-numbers +# Docs + +## Basics + + +``` + +**File bagian** (`parts/basics.md`) + +```md:line-numbers +Some getting started stuff. + +### Configuration + +Can be created using `.foorc.json`. +``` + +**Kode setara** + +```md:line-numbers +# Docs + +## Basics + +### Configuration + +Can be created using `.foorc.json`. +``` + +Format rentang baris yang dipilih dapat berupa: `{3,}`, `{,10}`, `{1,10}` + +Anda juga dapat menggunakan [VS Code region](https://code.visualstudio.com/docs/editor/codebasics#_folding) untuk hanya menyertakan bagian yang sesuai dari file kode. Anda dapat memberikan nama region kustom setelah `#` mengikuti filepath: + +**Input** + +```md:line-numbers +# Docs + +## Basics + + + +``` + +**File bagian** (`parts/basics.md`) + +```md:line-numbers + +## Usage Line 1 + +## Usage Line 2 + +## Usage Line 3 + +``` + +**Kode setara** + +```md:line-numbers +# Docs + +## Basics + +## Usage Line 1 + +## Usage Line 3 +``` + +::: warning +Perhatikan bahwa ini tidak menghasilkan error jika file Anda tidak ada. Oleh karena itu, saat menggunakan fitur ini pastikan konten dirender seperti yang diharapkan. +::: + +Alih-alih VS Code region, Anda juga dapat menggunakan header anchor untuk menyertakan bagian tertentu dari file. Misalnya, jika Anda memiliki header di file markdown Anda seperti ini: + +```md +## My Base Section + +Some content here. + +### My Sub Section + +Some more content here. + +## Another Section + +Content outside `My Base Section`. +``` + +Anda dapat menyertakan bagian `My Base Section` seperti ini: + +```md +## My Extended Section + +``` + +**Kode setara** + +```md +## My Extended Section + +Some content here. + +### My Sub Section + +Some more content here. +``` + +Di sini, `my-base-section` adalah id yang dihasilkan dari elemen heading. Jika tidak mudah ditebak, Anda dapat membuka file bagian di browser Anda dan klik anchor heading (simbol `#` di kiri heading saat dihover) untuk melihat id di bilah URL. Atau gunakan browser dev tools untuk memeriksa elemen. Alternatifnya, Anda juga dapat menentukan id ke file bagian seperti ini: + +```md +## My Base Section {#custom-id} +``` + +dan menyertakannya seperti ini: + +```md + +``` + +## Persamaan Matematika + +Ini saat ini bersifat opt-in. Untuk mengaktifkannya, Anda perlu menginstal `markdown-it-mathjax3` dan mengatur `markdown.math` ke `true` di file konfigurasi Anda: + +```sh +npm add -D markdown-it-mathjax3@^4 +``` + +```ts [.vitepress/config.ts] +export default { + markdown: { + math: true + } +} +``` + +**Input** + +```md +When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are +$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ + +**Maxwell's equations:** + +| equation | description | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero | +| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ | +| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ | +``` + +**Output** + +When $a \ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are +$$ x = {-b \pm \sqrt{b^2-4ac} \over 2a} $$ + +**Maxwell's equations:** + +| equation | description | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| $\nabla \cdot \vec{\mathbf{B}} = 0$ | divergence of $\vec{\mathbf{B}}$ is zero | +| $\nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} = \vec{\mathbf{0}}$ | curl of $\vec{\mathbf{E}}$ is proportional to the rate of change of $\vec{\mathbf{B}}$ | +| $\nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} = \frac{4\pi}{c}\vec{\mathbf{j}} \nabla \cdot \vec{\mathbf{E}} = 4 \pi \rho$ | _wha?_ | + +## Image Lazy Loading + +Anda dapat mengaktifkan lazy loading untuk setiap gambar yang ditambahkan melalui markdown dengan mengatur `lazyLoading` ke `true` di file konfigurasi Anda: + +```js +export default { + markdown: { + image: { + // image lazy loading dinonaktifkan secara default + lazyLoading: true + } + } +} +``` + +## Konfigurasi Lanjutan + +VitePress menggunakan [markdown-it](https://github.com/markdown-it/markdown-it) sebagai perender Markdown. Banyak ekstensi di atas diimplementasikan melalui plugin kustom. Anda dapat lebih menyesuaikan instance `markdown-it` menggunakan opsi `markdown` di `.vitepress/config.js`: + +```js +import { defineConfig } from 'vitepress' +import markdownItAnchor from 'markdown-it-anchor' +import markdownItFoo from 'markdown-it-foo' + +export default defineConfig({ + markdown: { + // opsi untuk markdown-it-anchor + // https://github.com/valeriangalliat/markdown-it-anchor#usage + anchor: { + permalink: markdownItAnchor.permalink.headerLink() + }, + + // opsi untuk @mdit-vue/plugin-toc + // https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options + toc: { level: [1, 2] }, + + config: (md) => { + // gunakan lebih banyak plugin markdown-it! + md.use(markdownItFoo) + } + } +}) +``` + +Lihat daftar lengkap properti yang dapat dikonfigurasi di [Referensi Konfigurasi: App Config](../reference/site-config#markdown). diff --git a/docs/id/guide/migration-from-vitepress-0.md b/docs/id/guide/migration-from-vitepress-0.md new file mode 100644 index 000000000..ffd249c96 --- /dev/null +++ b/docs/id/guide/migration-from-vitepress-0.md @@ -0,0 +1,23 @@ +# Migrasi dari VitePress 0.x + +Jika Anda berasal dari VitePress versi 0.x, ada beberapa breaking change karena fitur dan peningkatan baru. Ikuti panduan ini untuk melihat cara memigrasikan aplikasi Anda ke VitePress terbaru. + +## App Config + +- Fitur internasionalisasi belum diimplementasikan. + +## Theme Config + +- Opsi `sidebar` telah mengubah strukturnya. + - Key `children` sekarang dinamai `items`. + - Item tingkat atas saat ini mungkin tidak berisi `link`. Kami berencana untuk mengembalikannya. +- `repo`, `repoLabel`, `docsDir`, `docsBranch`, `editLinks`, `editLinkText` dihapus demi API yang lebih fleksibel. + - Untuk menambahkan tautan GitHub dengan ikon ke nav, gunakan fitur [Social Links](../reference/default-theme-nav#navigation-links). + - Untuk menambahkan fitur "Edit this page", gunakan fitur [Edit Link](../reference/default-theme-edit-link). +- Opsi `lastUpdated` sekarang dipisah menjadi `config.lastUpdated` dan `themeConfig.lastUpdatedText`. +- `carbonAds.carbon` diubah menjadi `carbonAds.code`. + +## Frontmatter Config + +- Opsi `home: true` telah berubah menjadi `layout: home`. Selain itu, banyak pengaturan terkait Homepage telah dimodifikasi untuk menyediakan fitur tambahan. Lihat [panduan Home Page](../reference/default-theme-home-page) untuk detailnya. +- Opsi `footer` dipindahkan ke [`themeConfig.footer`](../reference/default-theme-config#footer). diff --git a/docs/id/guide/migration-from-vuepress.md b/docs/id/guide/migration-from-vuepress.md new file mode 100644 index 000000000..ad4f7e68c --- /dev/null +++ b/docs/id/guide/migration-from-vuepress.md @@ -0,0 +1,30 @@ +# Migrasi dari VuePress + +## Config + +### Sidebar + +Sidebar tidak lagi otomatis diisi dari frontmatter. Anda dapat [membaca frontmatter sendiri](https://github.com/vuejs/vitepress/issues/572#issuecomment-1170116225) untuk mengisi sidebar secara dinamis. [Utilitas tambahan untuk ini](https://github.com/vuejs/vitepress/issues/96) mungkin disediakan di masa mendatang. + +## Markdown + +### Gambar + +Tidak seperti VuePress, VitePress menangani [`base`](./asset-handling#base-url) dari konfigurasi Anda secara otomatis saat Anda menggunakan gambar statis. + +Oleh karena itu, sekarang Anda dapat merender gambar tanpa tag `img`. + +```diff +- foo ++ ![foo](/foo.png) +``` + +::: warning +Untuk gambar dinamis Anda tetap memerlukan `withBase` seperti yang ditunjukkan di [panduan Base URL](./asset-handling#base-url). +::: + +Gunakan regex `` untuk mencari dan menggantinya dengan `![$2]($1)` untuk mengganti semua gambar dengan sintaks `![](...)`. + +--- + +selengkapnya menyusul... diff --git a/docs/id/guide/mpa-mode.md b/docs/id/guide/mpa-mode.md new file mode 100644 index 000000000..ac5f2498e --- /dev/null +++ b/docs/id/guide/mpa-mode.md @@ -0,0 +1,27 @@ +--- +description: Aktifkan mode MPA (Multi-Page Application) di VitePress untuk halaman tanpa JavaScript dengan performa awal yang lebih baik. +--- + +# Mode MPA + +Mode MPA (Multi-Page Application) dapat diaktifkan melalui command line dengan `vitepress build --mpa`, atau melalui konfigurasi dengan opsi `mpa: true`. + +Dalam mode MPA, semua halaman dirender tanpa JavaScript apa pun secara default. Hasilnya, situs produksi kemungkinan akan mendapatkan skor performa kunjungan awal yang lebih baik dari alat audit. + +Namun, karena tidak adanya navigasi SPA, tautan antar halaman akan menyebabkan reload halaman penuh. Navigasi setelah load dalam mode MPA tidak akan terasa seinstan dalam mode SPA. + +Perhatikan juga bahwa tanpa-JS-secara-default berarti Anda pada dasarnya menggunakan Vue murni sebagai bahasa templating sisi server. Tidak ada event handler yang akan dipasang di browser, sehingga tidak akan ada interaktivitas. Untuk memuat JavaScript sisi klien, Anda perlu menggunakan tag khusus ` + +# Hello +``` + +` +``` + +### Merender Konten Mentah + +Params yang diteruskan ke halaman akan diserialisasi dalam payload JavaScript klien, jadi Anda harus menghindari meneruskan data berat dalam params, misalnya konten Markdown mentah atau HTML yang diambil dari CMS remote. + +Sebagai gantinya, Anda dapat meneruskan konten tersebut ke setiap halaman menggunakan properti `content` pada setiap objek path: + +```js +export default { + async paths() { + const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + + return posts.map((post) => { + return { + params: { id: post.id }, + content: post.content // Markdown mentah atau HTML + } + }) + } +} +``` + +Kemudian, gunakan sintaks khusus berikut untuk merender konten sebagai bagian dari file Markdown itu sendiri: + +```md + +``` diff --git a/docs/id/guide/sitemap-generation.md b/docs/id/guide/sitemap-generation.md new file mode 100644 index 000000000..e971d511a --- /dev/null +++ b/docs/id/guide/sitemap-generation.md @@ -0,0 +1,62 @@ +--- +description: Hasilkan file sitemap.xml untuk situs VitePress Anda untuk meningkatkan keterlihatan mesin pencari. +--- + +# Pembuatan Sitemap + +VitePress hadir dengan dukungan bawaan untuk menghasilkan file `sitemap.xml` untuk situs Anda. Untuk mengaktifkannya, tambahkan yang berikut ke `.vitepress/config.js` Anda: + +```ts +export default { + sitemap: { + hostname: 'https://example.com' + } +} +``` + +Untuk memiliki tag `` di `sitemap.xml` Anda, Anda dapat mengaktifkan opsi [`lastUpdated`](../reference/default-theme-last-updated). + +## Opsi + +Dukungan sitemap didukung oleh modul [`sitemap`](https://www.npmjs.com/package/sitemap). Anda dapat meneruskan opsi apa pun yang didukung olehnya ke opsi `sitemap` di file konfigurasi Anda. Ini akan diteruskan langsung ke konstruktor `SitemapStream`. Lihat [dokumentasi `sitemap`](https://www.npmjs.com/package/sitemap#options-you-can-pass) untuk detail lebih lanjut. Contoh: + +```ts +export default { + sitemap: { + hostname: 'https://example.com', + lastmodDateOnly: false + } +} +``` + +Jika Anda menggunakan `base` di konfigurasi Anda, Anda harus menambahkannya ke opsi `hostname`: + +```ts +export default { + base: '/my-site/', + sitemap: { + hostname: 'https://example.com/my-site/' + } +} +``` + +## Hook `transformItems` + +Anda dapat menggunakan hook `sitemap.transformItems` untuk memodifikasi item sitemap sebelum ditulis ke file `sitemap.xml`. Hook ini dipanggil dengan array item sitemap dan mengharapkan array item sitemap dikembalikan. Contoh: + +```ts +export default { + sitemap: { + hostname: 'https://example.com', + transformItems: (items) => { + // tambahkan item baru atau modifikasi/filter item yang ada + items.push({ + url: '/extra-page', + changefreq: 'monthly', + priority: 0.8 + }) + return items + } + } +} +``` diff --git a/docs/id/guide/ssr-compat.md b/docs/id/guide/ssr-compat.md new file mode 100644 index 000000000..32abc6966 --- /dev/null +++ b/docs/id/guide/ssr-compat.md @@ -0,0 +1,135 @@ +--- +description: Pastikan komponen tema VitePress dan kode kustom Anda kompatibel dengan server-side rendering. +outline: deep +--- + +# Kompatibilitas SSR + +VitePress melakukan pre-render aplikasi di Node.js selama build produksi, menggunakan kemampuan Server-Side Rendering (SSR) Vue. Ini berarti semua kode kustom di komponen tema tunduk pada Kompatibilitas SSR. + +[Bagian SSR di dokumen resmi Vue](https://vuejs.org/guide/scaling-up/ssr.html) menyediakan lebih banyak konteks tentang apa itu SSR, hubungan antara SSR / SSG, dan catatan umum tentang menulis kode yang ramah SSR. Aturan umumnya adalah hanya mengakses browser / DOM API di hook `beforeMount` atau `mounted` komponen Vue. + +## `` + +Jika Anda menggunakan atau mendemokan komponen yang tidak ramah SSR (misalnya, berisi custom directive), Anda dapat membungkusnya di dalam komponen bawaan ``: + +```md + + + +``` + +## Library yang Mengakses Browser API Saat Import + +Beberapa komponen atau library mengakses browser API **saat import**. Untuk menggunakan kode yang mengasumsikan lingkungan browser saat import, Anda perlu mengimpornya secara dinamis. + +### Mengimpor di Hook Mounted + +```vue + +``` + +### Conditional Import + +Anda juga dapat mengimpor dependensi secara kondisional menggunakan flag `import.meta.env.SSR` (bagian dari [Vite env variables](https://vitejs.dev/guide/env-and-mode.html#env-variables)): + +```js +if (!import.meta.env.SSR) { + import('./lib-that-access-window-on-import').then((module) => { + // gunakan kode + }) +} +``` + +Karena [`Theme.enhanceApp`](./custom-theme#theme-interface) dapat bersifat async, Anda dapat mengimpor dan mendaftarkan plugin Vue yang mengakses browser API saat import secara kondisional: + +```js [.vitepress/theme/index.js] +/** @type {import('vitepress').Theme} */ +export default { + // ... + async enhanceApp({ app }) { + if (!import.meta.env.SSR) { + const plugin = await import('plugin-that-access-window-on-import') + app.use(plugin.default) + } + } +} +``` + +Jika Anda menggunakan TypeScript: +```ts [.vitepress/theme/index.ts] +import type { Theme } from 'vitepress' + +export default { + // ... + async enhanceApp({ app }) { + if (!import.meta.env.SSR) { + const plugin = await import('plugin-that-access-window-on-import') + app.use(plugin.default) + } + } +} satisfies Theme +``` + +### `defineClientComponent` + +VitePress menyediakan helper untuk mengimpor komponen Vue yang mengakses browser API saat import. + +```vue + + + +``` + +Anda juga dapat meneruskan props/children/slots ke komponen target: + +```vue + + + +``` + +Komponen target hanya akan diimpor di hook mounted dari komponen wrapper. diff --git a/docs/id/guide/using-vue.md b/docs/id/guide/using-vue.md new file mode 100644 index 000000000..107fc0311 --- /dev/null +++ b/docs/id/guide/using-vue.md @@ -0,0 +1,295 @@ +--- +description: Gunakan komponen Vue dan fitur templating dinamis langsung di dalam file Markdown di VitePress. +--- + +# Menggunakan Vue di Markdown + +Di VitePress, setiap file Markdown dikompilasi menjadi HTML dan kemudian diproses sebagai [Vue Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html). Ini berarti Anda dapat menggunakan fitur Vue apa pun di dalam Markdown, termasuk templating dinamis, menggunakan komponen Vue, atau logika komponen Vue dalam halaman apa pun dengan menambahkan tag ` + +## Konten Markdown + +Hitungannya: {{ count }} + + + + +``` + +::: warning Hindari ` +``` + +## Menggunakan Teleports + +VitePress saat ini memiliki dukungan SSG untuk teleport ke body saja. Untuk target lain, Anda dapat membungkusnya di dalam komponen bawaan `` atau menyuntikkan markup teleport ke lokasi yang benar di HTML halaman akhir Anda melalui hook [`postRender`](../reference/site-config#postrender). + + + +::: details +<<< @/components/ModalDemo.vue +::: + +```md + + +
+ // ... +
+ + +``` + + + + + + +## Dukungan VS Code IntelliSense + + + +Vue menyediakan dukungan IntelliSense bawaan melalui [plugin Vue - Official VS Code](https://marketplace.visualstudio.com/items?itemName=Vue.volar). Namun, untuk mengaktifkannya untuk file `.md`, Anda perlu melakukan beberapa penyesuaian pada file konfigurasi. + + +1. Tambahkan pattern `.md` ke opsi `include` dan `vueCompilerOptions.vitePressExtensions` di file tsconfig/jsconfig: + +::: code-group +```json [tsconfig.json] +{ + "include": [ + "docs/**/*.ts", + "docs/**/*.vue", + "docs/**/*.md", + ], + "vueCompilerOptions": { + "vitePressExtensions": [".md"], + }, +} +``` +::: + +2. Tambahkan `markdown` ke opsi `vue.server.includeLanguages` di pengaturan VS Code: + +::: code-group +```json [.vscode/settings.json] +{ + "vue.server.includeLanguages": ["vue", "markdown"] +} +``` +::: diff --git a/docs/id/guide/what-is-vitepress.md b/docs/id/guide/what-is-vitepress.md new file mode 100644 index 000000000..a6b013fde --- /dev/null +++ b/docs/id/guide/what-is-vitepress.md @@ -0,0 +1,61 @@ +--- +description: VitePress adalah generator situs statis yang dirancang untuk membangun situs cepat dan berfokus pada konten berbasis Vite dan Vue. +--- + +# Apa Itu VitePress? + +VitePress adalah [Static Site Generator](https://en.wikipedia.org/wiki/Static_site_generator) (SSG) yang dirancang untuk membangun situs cepat yang berfokus pada konten. Secara singkat, VitePress mengambil konten sumber Anda yang ditulis dalam [Markdown](https://en.wikipedia.org/wiki/Markdown), menerapkan tema padanya, dan menghasilkan halaman HTML statis yang dapat dideploy dengan mudah di mana saja. + +
+ +Hanya ingin mencobanya? Langsung ke [Panduan Cepat](./getting-started). + +
+ +## Use Cases + +- **Dokumentasi** + + VitePress hadir dengan tema default yang dirancang untuk dokumentasi teknis. Tema ini mendukung halaman yang sedang Anda baca saat ini, beserta dokumentasi untuk [Vite](https://vitejs.dev/), [Rollup](https://rollupjs.org/), [Pinia](https://pinia.vuejs.org/), [VueUse](https://vueuse.org/), [Vitest](https://vitest.dev/), [D3](https://d3js.org/), [UnoCSS](https://unocss.dev/), [Iconify](https://iconify.design/) dan [banyak lagi](https://github.com/search?q=/%22vitepress%22:+/+path:/(?:package%7Cdeno)%5C.jsonc?$/+NOT+is:fork+NOT+is:archived&type=code). + + [Dokumentasi resmi Vue.js](https://vuejs.org/) juga berbasis VitePress, tetapi menggunakan tema kustom yang dibagikan di antara berbagai terjemahan. + +- **Blog, Portofolio, dan Situs Marketing** + + VitePress mendukung [tema yang sepenuhnya dikustomisasi](./custom-theme), dengan pengalaman developer setara aplikasi Vite + Vue standar. Dibangun di atas Vite juga berarti Anda dapat langsung memanfaatkan plugin Vite dari ekosistemnya yang kaya. Selain itu, VitePress menyediakan API yang fleksibel untuk [memuat data](./data-loading) (lokal atau remote) dan [menghasilkan rute secara dinamis](./routing#dynamic-routes). Anda dapat menggunakannya untuk membangun hampir apa pun selama data dapat ditentukan pada waktu build. + + [Blog resmi Vue.js](https://blog.vuejs.org/) adalah blog sederhana yang menghasilkan halaman indeks berdasarkan konten lokal. + +## Developer Experience + +VitePress bertujuan memberikan Developer Experience (DX) yang hebat saat bekerja dengan konten Markdown. + +- **[Berbasis Vite:](https://vitejs.dev/)** server langsung menyala, dengan perubahan selalu langsung tercermin (<100ms) tanpa reload halaman. + +- **[Ekstensi Markdown Bawaan:](./markdown)** Frontmatter, tabel, syntax highlighting... semua tersedia. Secara khusus, VitePress menyediakan banyak fitur lanjutan untuk bekerja dengan blok kode, menjadikannya ideal untuk dokumentasi yang sangat teknis. + +- **[Markdown yang Diperkuat Vue:](./using-vue)** setiap halaman Markdown juga merupakan Vue [Single-File Component](https://vuejs.org/guide/scaling-up/sfc.html), berkat kompatibilitas sintaks 100% template Vue dengan HTML. Anda dapat menyematkan interaktivitas dalam konten statis Anda menggunakan fitur templating Vue atau komponen Vue yang diimpor. + +## Performa + +Tidak seperti banyak SSG tradisional di mana setiap navigasi menghasilkan reload halaman penuh, situs yang dihasilkan oleh VitePress menyajikan HTML statis pada kunjungan awal, tetapi menjadi [Single Page Application](https://en.wikipedia.org/wiki/Single-page_application) (SPA) untuk navigasi selanjutnya di dalam situs. Model ini, menurut kami, memberikan keseimbangan optimal untuk performa: + +- **Initial Load Cepat** + + Kunjungan awal ke halaman mana pun akan disajikan HTML statis yang telah di-pre-render untuk kecepatan loading yang cepat dan SEO optimal. Halaman kemudian memuat bundel JavaScript yang mengubah halaman menjadi Vue SPA ("hydration"). Bertentangan dengan asumsi umum bahwa hydration SPA lambat, proses ini sebenarnya sangat cepat berkat performa mentah Vue 3 dan optimasi compiler. Pada [PageSpeed Insights](https://pagespeed.web.dev/report?url=https%3A%2F%2Fvitepress.dev%2F), situs VitePress umum mencapai skor performa hampir sempurna bahkan pada perangkat seluler kelas bawah dengan jaringan lambat. + +- **Navigasi Setelah Load Cepat** + + Lebih penting lagi, model SPA menghasilkan pengalaman pengguna yang lebih baik **setelah** initial load. Navigasi selanjutnya di dalam situs tidak lagi menyebabkan reload halaman penuh. Sebaliknya, konten halaman yang masuk akan diambil dan diperbarui secara dinamis. VitePress juga secara otomatis melakukan pre-fetch potongan halaman untuk tautan yang berada dalam viewport. Dalam kebanyakan kasus, navigasi setelah load akan terasa instan. + +- **Interaktivitas Tanpa Dampak Negatif** + + Untuk dapat menghidrasi bagian Vue dinamis yang tertanam di dalam Markdown statis, setiap halaman Markdown diproses sebagai komponen Vue dan dikompilasi menjadi JavaScript. Ini mungkin terdengar tidak efisien, tetapi compiler Vue cukup pintar untuk memisahkan bagian statis dan dinamis, meminimalkan biaya hydration dan ukuran payload. Untuk initial load halaman, bagian statis secara otomatis dihilangkan dari payload JavaScript dan dilewati selama hydration. + +## Bagaimana dengan VuePress? + +VitePress adalah penerus spiritual VuePress 1. VuePress 1 asli berbasis Vue 2 dan webpack. Dengan Vue 3 dan Vite di baliknya, VitePress memberikan DX yang jauh lebih baik, performa produksi yang lebih baik, tema default yang lebih halus, dan API kustomisasi yang lebih fleksibel. + +Perbedaan API antara VitePress dan VuePress 1 sebagian besar terletak pada tema dan kustomisasi. Jika Anda menggunakan VuePress 1 dengan tema default, seharusnya relatif mudah untuk bermigrasi ke VitePress. + +Mempertahankan dua SSG secara paralel tidak berkelanjutan, sehingga tim Vue telah memutuskan untuk fokus pada VitePress sebagai SSG utama yang direkomendasikan dalam jangka panjang. Sekarang VuePress 1 telah deprecated, dan VuePress 2 telah diserahkan ke tim komunitas VuePress untuk pengembangan dan pemeliharaan lebih lanjut. diff --git a/docs/id/index.md b/docs/id/index.md new file mode 100644 index 000000000..5eca860c5 --- /dev/null +++ b/docs/id/index.md @@ -0,0 +1,36 @@ +--- +description: VitePress adalah generator situs statis berbasis Vite dan Vue untuk membuat situs dokumentasi yang indah dari Markdown. +layout: home + +hero: + name: VitePress + text: Generator Situs Statis Berbasis Vite dan Vue + tagline: Dari Markdown ke dokumentasi indah dalam hitungan menit + actions: + - theme: brand + text: Apa itu VitePress? + link: ./guide/what-is-vitepress + - theme: alt + text: Mulai Cepat + link: ./guide/getting-started + - theme: alt + text: GitHub + link: https://github.com/vuejs/vitepress + image: + src: /vitepress-logo-large.svg + alt: VitePress + +features: + - icon: 📝 + title: Fokus pada konten Anda + details: Buat situs dokumentasi yang indah dengan mudah, cukup dengan markdown. + - icon: + title: Nikmati Vite DX + details: Server menyala instan, hot update secepat kilat, dan manfaatkan plugin ekosistem Vite. + - icon: + title: Kustomisasi dengan Vue + details: Gunakan sintaks dan komponen Vue langsung di markdown, atau bangun tema kustom dengan Vue. + - icon: 🚀 + title: Bangun situs cepat + details: Muat awal yang cepat dengan HTML statis, navigasi cepat setelah muat dengan client-side routing. +--- diff --git a/docs/id/reference/cli.md b/docs/id/reference/cli.md new file mode 100644 index 000000000..034e8471a --- /dev/null +++ b/docs/id/reference/cli.md @@ -0,0 +1,77 @@ +--- +description: Referensi perintah CLI VitePress termasuk dev, build, preview, dan init. +--- + +# Command Line Interface + +## `vitepress dev` + +Memulai server pengembangan VitePress menggunakan direktori yang ditentukan sebagai root. Default ke direktori saat ini. Perintah `dev` juga dapat dihilangkan ketika dijalankan di direktori saat ini. + +### Penggunaan + +```sh +# mulai di direktori saat ini, tanpa menuliskan `dev` +vitepress + +# mulai di subdirektori +vitepress dev [root] +``` + +### Opsi + +| Opsi | Deskripsi | +| --------------- | ------------------------------------------------------------------------ | +| `--open [path]` | Buka browser saat startup (`boolean \| string`) | +| `--port ` | Tentukan port (`number`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--cors` | Aktifkan CORS | +| `--strictPort` | Keluar jika port yang ditentukan sedang digunakan (`boolean`) | +| `--force` | Paksa optimizer mengabaikan cache dan melakukan re-bundle (`boolean`) | + +## `vitepress build` + +Membangun situs VitePress untuk production. + +### Penggunaan + +```sh +vitepress build [root] +``` + +### Opsi + +| Opsi | Deskripsi | +| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| `--mpa` (eksperimental) | Build dalam [mode MPA](../guide/mpa-mode) tanpa client-side hydration (`boolean`) | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--target ` | Target transpile (default: `"modules"`) (`string`) | +| `--outDir ` | Direktori output relatif terhadap **cwd** (default: `/.vitepress/dist`) (`string`) | +| `--assetsInlineLimit ` | Batas aset statis yang di-inline sebagai base64 dalam byte (default: `4096`) (`number`) | + +## `vitepress preview` + +Pratinjau hasil build production secara lokal. + +### Penggunaan + +```sh +vitepress preview [root] +``` + +### Opsi + +| Opsi | Deskripsi | +| --------------- | ---------------------------------------- | +| `--base ` | Public base path (default: `/`) (`string`) | +| `--port ` | Tentukan port (`number`) | + +## `vitepress init` + +Memulai [Setup Wizard](../guide/getting-started#setup-wizard) di direktori saat ini. + +### Penggunaan + +```sh +vitepress init +``` diff --git a/docs/id/reference/default-theme-badge.md b/docs/id/reference/default-theme-badge.md new file mode 100644 index 000000000..fcb0df64b --- /dev/null +++ b/docs/id/reference/default-theme-badge.md @@ -0,0 +1,73 @@ +--- +description: Gunakan komponen Badge untuk menambahkan label status pada heading di dokumentasi VitePress. +--- + +# Badge + +Dengan Badge, Anda dapat menambahkan status pada heading. Misalnya, ini dapat berguna untuk menentukan jenis bagian, atau versi yang didukung. + +## Penggunaan + +Anda dapat menggunakan komponen `Badge` yang tersedia secara global. + +```html +### Judul +### Judul +### Judul +### Judul +``` + +Kode di atas menghasilkan tampilan seperti: + +### Title +### Title +### Title +### Title + +## Custom Children + +`` menerima `children`, yang akan ditampilkan di dalam badge. + +```html +### Judul custom element +``` + +### Title custom element + +## Menyesuaikan Warna Tipe + +Anda dapat menyesuaikan gaya badge dengan menimpa variabel css. Berikut adalah nilai default: + +```css +:root { + --vp-badge-info-border: transparent; + --vp-badge-info-text: var(--vp-c-text-2); + --vp-badge-info-bg: var(--vp-c-default-soft); + + --vp-badge-tip-border: transparent; + --vp-badge-tip-text: var(--vp-c-brand-1); + --vp-badge-tip-bg: var(--vp-c-brand-soft); + + --vp-badge-warning-border: transparent; + --vp-badge-warning-text: var(--vp-c-warning-1); + --vp-badge-warning-bg: var(--vp-c-warning-soft); + + --vp-badge-danger-border: transparent; + --vp-badge-danger-text: var(--vp-c-danger-1); + --vp-badge-danger-bg: var(--vp-c-danger-soft); +} +``` + +## `` + +Komponen `` menerima props berikut: + +```ts +interface Props { + // Ketika `` diberikan, nilai ini diabaikan. + text?: string + + // Default ke `tip`. + type?: 'info' | 'tip' | 'warning' | 'danger' +} +``` diff --git a/docs/id/reference/default-theme-carbon-ads.md b/docs/id/reference/default-theme-carbon-ads.md new file mode 100644 index 000000000..2ab79791b --- /dev/null +++ b/docs/id/reference/default-theme-carbon-ads.md @@ -0,0 +1,29 @@ +--- +description: Integrasikan Carbon Ads ke situs VitePress Anda menggunakan dukungan bawaan tema default. +--- + +# Carbon Ads + +VitePress memiliki dukungan bawaan untuk [Carbon Ads](https://www.carbonads.net/). Dengan mendefinisikan kredensial Carbon Ads di config, VitePress akan menampilkan iklan pada halaman. + +```js +export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement', + format: 'classic' + } + } +} +``` + +Nilai-nilai ini digunakan untuk memanggil script CDN carbon seperti yang ditunjukkan di bawah. + +Opsi `format` mendukung `classic`, `responsive`, dan `cover`. + +```js +`//cdn.carbonads.com/carbon.js?serve=${code}&placement=${placement}&format=${format}` +``` + +Untuk mempelajari lebih lanjut tentang konfigurasi Carbon Ads, kunjungi [situs Carbon Ads](https://www.carbonads.net/). diff --git a/docs/id/reference/default-theme-config.md b/docs/id/reference/default-theme-config.md new file mode 100644 index 000000000..6aa0a3521 --- /dev/null +++ b/docs/id/reference/default-theme-config.md @@ -0,0 +1,500 @@ +--- +description: Referensi semua opsi konfigurasi yang tersedia untuk tema default VitePress. +--- + +# Konfigurasi Tema Default + +Dengan konfigurasi tema, Anda dapat menyesuaikan tema. Anda dapat mendefinisikan konfigurasi tema melalui opsi `themeConfig` di file config: + +```ts +export default { + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // Konfigurasi terkait tema. + themeConfig: { + logo: '/logo.svg', + nav: [...], + sidebar: { ... } + } +} +``` + +**Opsi yang didokumentasikan di halaman ini hanya berlaku untuk tema default.** Tema yang berbeda mengharapkan konfigurasi tema yang berbeda. Ketika menggunakan tema kustom, objek konfigurasi tema akan diteruskan ke tema sehingga tema dapat menentukan perilaku kondisional berdasarkan konfigurasi tersebut. + +## i18nRouting + +- Tipe: `boolean` + +Mengubah locale misalnya ke `zh` akan mengubah URL dari `/foo` (atau `/en/foo/`) menjadi `/zh/foo`. Anda dapat menonaktifkan perilaku ini dengan mengatur `themeConfig.i18nRouting` ke `false`. + +## logo + +- Tipe: `ThemeableImage` + +File logo untuk ditampilkan di bilah nav, tepat sebelum judul situs. Menerima string path, atau objek untuk mengatur logo yang berbeda untuk mode terang/gelap. + +```ts +export default { + themeConfig: { + logo: '/logo.svg' + } +} +``` + +```ts +type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } +``` + +## siteTitle + +- Tipe: `string | false` + +Anda dapat menyesuaikan item ini untuk mengganti judul situs default (`title` di config aplikasi) di nav. Ketika diatur ke `false`, judul di nav akan dinonaktifkan. Berguna ketika Anda memiliki `logo` yang sudah berisi teks judul situs. + +```ts +export default { + themeConfig: { + siteTitle: 'Hello World' + } +} +``` + +## nav + +- Tipe: `NavItem` + +Konfigurasi untuk item menu nav. Detail lebih lanjut di [Default Theme: Nav](./default-theme-nav#navigation-links). + +```ts +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { text: 'Item A', link: '/item-1' }, + { text: 'Item B', link: '/item-2' }, + { text: 'Item C', link: '/item-3' } + ] + } + ] + } +} +``` + +```ts +type NavItem = NavItemWithLink | NavItemWithChildren + +interface NavItemWithLink { + text: string + link: string | ((payload: PageData) => string) + activeMatch?: string + target?: string + rel?: string + noIcon?: boolean +} + +interface NavItemChildren { + text?: string + items: NavItemWithLink[] +} + +interface NavItemWithChildren { + text?: string + items: (NavItemChildren | NavItemWithLink)[] + activeMatch?: string +} +``` + +## sidebar + +- Tipe: `Sidebar` + +Konfigurasi untuk item menu sidebar. Detail lebih lanjut di [Default Theme: Sidebar](./default-theme-sidebar). + +```ts +export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + { text: 'Introduction', link: '/introduction' }, + { text: 'Getting Started', link: '/getting-started' }, + ... + ] + } + ] + } +} +``` + +```ts +export type Sidebar = SidebarItem[] | SidebarMulti + +export interface SidebarMulti { + [path: string]: SidebarItem[] | { items: SidebarItem[]; base: string } +} + +export type SidebarItem = { + /** + * Label teks dari item. + */ + text?: string + + /** + * Tautan dari item. + */ + link?: string + + /** + * Children dari item. + */ + items?: SidebarItem[] + + /** + * Jika tidak ditentukan, grup tidak dapat diciutkan. + * + * Jika `true`, grup dapat diciutkan dan diciutkan secara default + * + * Jika `false`, grup dapat diciutkan tetapi diperluas secara default + */ + collapsed?: boolean + + /** + * Path dasar untuk item children. + */ + base?: string + + /** + * Menyesuaikan teks yang muncul di footer halaman sebelumnya/berikutnya. + */ + docFooterText?: string + + rel?: string + target?: string +} +``` + +## aside + +- Tipe: `boolean | 'left'` +- Default: `true` +- Dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#aside) + +Mengatur nilai ini ke `false` mencegah rendering kontainer aside.\ +Mengatur nilai ini ke `true` merender aside di sebelah kanan.\ +Mengatur nilai ini ke `left` merender aside di sebelah kiri. + +Jika Anda ingin menonaktifkannya untuk semua viewport, sebaiknya gunakan `outline: false`. + +## outline + +- Tipe: `Outline | Outline['level'] | false` +- Level dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#outline) + +Mengatur nilai ini ke `false` mencegah rendering kontainer outline. Lihat interface ini untuk detail lebih lanjut: + +```ts +interface Outline { + /** + * Level heading yang akan ditampilkan di outline. + * Angka tunggal berarti hanya heading pada level tersebut yang akan ditampilkan. + * Jika tuple diberikan, angka pertama adalah level minimum dan angka kedua adalah level maksimum. + * `'deep'` sama dengan `[2, 6]`, yang berarti semua heading dari `

` hingga `

` akan ditampilkan. + * + * @default 2 + */ + level?: number | [number, number] | 'deep' + + /** + * Judul yang akan ditampilkan pada outline. + * + * @default 'On this page' + */ + label?: string +} +``` + +## socialLinks + +- Tipe: `SocialLink[]` + +Anda dapat mendefinisikan opsi ini untuk menampilkan tautan akun sosial Anda dengan ikon di nav. + +```ts +export default { + themeConfig: { + socialLinks: [ + // Anda dapat menambahkan ikon apa pun dari simple-icons (https://simpleicons.org/): + { icon: 'github', link: 'https://github.com/vuejs/vitepress' }, + { icon: 'twitter', link: '...' }, + // Anda juga dapat menambahkan ikon kustom dengan mengirimkan SVG sebagai string: + { + icon: { + svg: 'Dribbble' + }, + link: '...', + // Anda dapat menyertakan label kustom untuk aksesibilitas juga (opsional tetapi direkomendasikan): + ariaLabel: 'cool link' + } + ] + } +} +``` + +```ts +interface SocialLink { + icon: string | { svg: string } + link: string + ariaLabel?: string +} +``` + +## footer + +- Tipe: `Footer` +- Dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#footer) + +Konfigurasi footer. Anda dapat menambahkan pesan atau teks hak cipta di footer, namun, ini hanya akan ditampilkan ketika halaman tidak memiliki sidebar. Ini karena pertimbangan desain. + +```ts +export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } +} +``` + +```ts +export interface Footer { + message?: string + copyright?: string +} +``` + +## editLink + +- Tipe: `EditLink` +- Dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#editlink) + +Edit Link dapat digunakan untuk menampilkan tautan untuk mengedit halaman pada layanan manajemen Git seperti GitHub atau GitLab. Lihat [Default Theme: Edit Link](./default-theme-edit-link) untuk detail lebih lanjut. + +```ts +export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'Edit this page on GitHub' + } + } +} +``` + +```ts +export interface EditLink { + pattern: string + text?: string +} +``` + +## lastUpdated + +- Tipe: `LastUpdatedOptions` + +Memungkinkan penyesuaian untuk teks last updated dan format tanggal. + +```ts +export default { + themeConfig: { + lastUpdated: { + text: 'Updated at', + formatOptions: { + dateStyle: 'full', + timeStyle: 'medium' + } + } + } +} +``` + +```ts +export interface LastUpdatedOptions { + /** + * @default 'Last updated' + */ + text?: string + + /** + * @default + * { dateStyle: 'short', timeStyle: 'short' } + */ + formatOptions?: Intl.DateTimeFormatOptions & { forceLocale?: boolean } +} +``` + +## algolia + +- Tipe: `AlgoliaSearch` + +Opsi untuk mendukung pencarian di situs dokumentasi Anda menggunakan [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Pelajari lebih lanjut di [Default Theme: Search](./default-theme-search) + +```ts +export interface AlgoliaSearchOptions extends DocSearchProps { + locales?: Record> +} +``` + +Lihat opsi lengkap [di sini](https://github.com/vuejs/vitepress/blob/main/types/docsearch.d.ts). + +## carbonAds {#carbon-ads} + +- Tipe: `CarbonAdsOptions` + +Opsi untuk menampilkan [Carbon Ads](https://www.carbonads.net/). + +```ts +export default { + themeConfig: { + carbonAds: { + code: 'your-carbon-code', + placement: 'your-carbon-placement' + format: 'classic' + } + } +} +``` + +```ts +export interface CarbonAdsOptions { + code: string + placement: string + format?: 'classic' | 'responsive' | 'cover' +} +``` + +Pelajari lebih lanjut di [Default Theme: Carbon Ads](./default-theme-carbon-ads) + +## docFooter + +- Tipe: `DocFooter` + +Dapat digunakan untuk menyesuaikan teks yang muncul di atas tautan sebelumnya dan berikutnya. Berguna jika tidak menulis dokumen dalam bahasa Inggris. Juga dapat digunakan untuk menonaktifkan tautan prev/next secara global. Jika Anda ingin mengaktifkan/menonaktifkan tautan prev/next secara selektif, Anda dapat menggunakan [frontmatter](./default-theme-prev-next-links). + +```ts +export default { + themeConfig: { + docFooter: { + prev: 'Pagina prior', + next: 'Proxima pagina' + } + } +} +``` + +```ts +export interface DocFooter { + prev?: string | false + next?: string | false +} +``` + +## darkModeSwitchLabel + +- Tipe: `string` +- Default: `Appearance` + +Dapat digunakan untuk menyesuaikan label tombol mode gelap. Label ini hanya ditampilkan di tampilan mobile. + +## lightModeSwitchTitle + +- Tipe: `string` +- Default: `Switch to light theme` + +Dapat digunakan untuk menyesuaikan judul tombol mode terang yang muncul saat hover. + +## darkModeSwitchTitle + +- Tipe: `string` +- Default: `Switch to dark theme` + +Dapat digunakan untuk menyesuaikan judul tombol mode gelap yang muncul saat hover. + +## sidebarMenuLabel + +- Tipe: `string` +- Default: `Menu` + +Dapat digunakan untuk menyesuaikan label menu sidebar. Label ini hanya ditampilkan di tampilan mobile. + +## returnToTopLabel + +- Tipe: `string` +- Default: `Return to top` + +Dapat digunakan untuk menyesuaikan label tombol kembali ke atas. Label ini hanya ditampilkan di tampilan mobile. + +## langMenuLabel + +- Tipe: `string` +- Default: `Change language` + +Dapat digunakan untuk menyesuaikan aria-label tombol pengganti bahasa di navbar. Ini hanya digunakan jika Anda menggunakan [i18n](../guide/i18n). + +## skipToContentLabel + +- Tipe: `string` +- Default: `Skip to content` + +Dapat digunakan untuk menyesuaikan label tautan skip to content. Tautan ini ditampilkan ketika pengguna menavigasi situs menggunakan keyboard. + +## externalLinkIcon + +- Tipe: `boolean` +- Default: `false` + +Apakah akan menampilkan ikon tautan eksternal di samping tautan eksternal di markdown. + +## `useLayout` + +Mengembalikan data terkait layout. Objek yang dikembalikan memiliki tipe berikut: + +```ts +interface { + isHome: ComputedRef + + sidebar: Readonly> + sidebarGroups: ComputedRef + hasSidebar: ComputedRef + isSidebarEnabled: ComputedRef + + hasAside: ComputedRef + leftAside: ComputedRef + + headers: Readonly> + hasLocalNav: ComputedRef +} +``` + +**Contoh:** + +```vue + + + +``` diff --git a/docs/id/reference/default-theme-edit-link.md b/docs/id/reference/default-theme-edit-link.md new file mode 100644 index 000000000..047e9ce7d --- /dev/null +++ b/docs/id/reference/default-theme-edit-link.md @@ -0,0 +1,64 @@ +--- +description: Tampilkan tautan edit pada halaman dokumen untuk memungkinkan pengguna menyarankan perubahan di GitHub atau GitLab. +--- + +# Edit Link + +## Konfigurasi Tingkat Situs + +Edit Link dapat digunakan untuk menampilkan tautan untuk mengedit halaman pada layanan manajemen Git seperti GitHub atau GitLab. Untuk mengaktifkannya, tambahkan opsi `themeConfig.editLink` ke config Anda. + +```js +export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path' + } + } +} +``` + +Opsi `pattern` mendefinisikan struktur URL untuk tautan, dan `:path` akan diganti dengan path halaman. + +Anda juga dapat memberikan fungsi murni yang menerima [`PageData`](./runtime-api#usedata) sebagai argumen dan mengembalikan string URL. + +```js +export default { + themeConfig: { + editLink: { + pattern: ({ filePath }) => { + if (filePath.startsWith('packages/')) { + return `https://github.com/acme/monorepo/edit/main/${filePath}` + } else { + return `https://github.com/acme/monorepo/edit/main/docs/${filePath}` + } + } + } + } +} +``` + +Fungsi ini tidak boleh memiliki side-effect atau mengakses apa pun di luar cakupannya karena akan diserialisasi dan dijalankan di browser. + +Secara default, ini akan menambahkan teks tautan "Edit this page" di bagian bawah halaman dokumen. Anda dapat menyesuaikan teks ini dengan mendefinisikan opsi `text`. + +```js +export default { + themeConfig: { + editLink: { + pattern: 'https://github.com/vuejs/vitepress/edit/main/docs/:path', + text: 'Edit this page on GitHub' + } + } +} +``` + +## Konfigurasi Frontmatter + +Ini dapat dinonaktifkan per halaman menggunakan opsi `editLink` di frontmatter: + +```yaml +--- +editLink: false +--- +``` diff --git a/docs/id/reference/default-theme-footer.md b/docs/id/reference/default-theme-footer.md new file mode 100644 index 000000000..b885c0906 --- /dev/null +++ b/docs/id/reference/default-theme-footer.md @@ -0,0 +1,57 @@ +--- +description: Konfigurasikan footer global yang ditampilkan di bagian bawah halaman VitePress. +--- + +# Footer + +VitePress akan menampilkan footer global di bagian bawah halaman ketika `themeConfig.footer` tersedia. + +```ts +export default { + themeConfig: { + footer: { + message: 'Released under the MIT License.', + copyright: 'Copyright © 2019-present Evan You' + } + } +} +``` + +```ts +export interface Footer { + // Pesan yang ditampilkan tepat sebelum copyright. + message?: string + + // Teks copyright sebenarnya. + copyright?: string +} +``` + +Konfigurasi di atas juga mendukung string HTML. Jadi, misalnya, jika Anda ingin mengonfigurasi teks footer agar memiliki beberapa tautan, Anda dapat menyesuaikan konfigurasi sebagai berikut: + +```ts +export default { + themeConfig: { + footer: { + message: 'Dirilis di bawah Lisensi MIT.', + copyright: 'Hak Cipta © 2019-sekarang Evan You' + } + } +} +``` + +::: warning +Hanya elemen inline yang dapat digunakan di `message` dan `copyright` karena dirender di dalam elemen `

`. Jika Anda ingin menambahkan elemen block, pertimbangkan untuk menggunakan slot [`layout-bottom`](../guide/extending-default-theme#layout-slots). +::: + +Perhatikan bahwa footer tidak akan ditampilkan ketika [SideBar](./default-theme-sidebar) terlihat. + +## Konfigurasi Frontmatter + +Ini dapat dinonaktifkan per halaman menggunakan opsi `footer` di frontmatter: + +```yaml +--- +footer: false +--- +``` diff --git a/docs/id/reference/default-theme-home-page.md b/docs/id/reference/default-theme-home-page.md new file mode 100644 index 000000000..7b96ab592 --- /dev/null +++ b/docs/id/reference/default-theme-home-page.md @@ -0,0 +1,199 @@ +--- +description: Konfigurasikan layout halaman beranda tema default VitePress dengan bagian hero, fitur, dan konten kustom. +--- + +# Halaman Beranda + +Tema default VitePress menyediakan layout homepage, yang juga dapat Anda lihat digunakan di [beranda situs ini](../). Anda dapat menggunakannya di halaman mana pun dengan menentukan `layout: home` di [frontmatter](./frontmatter-config). + +```yaml +--- +layout: home +--- +``` + +Namun, opsi ini saja tidak akan banyak berpengaruh. Anda dapat menambahkan beberapa "bagian" pra-template yang berbeda ke beranda dengan mengatur opsi tambahan lainnya seperti `hero` dan `features`. + +## Bagian Hero + +Bagian Hero muncul di bagian atas beranda. Berikut cara Anda mengonfigurasi bagian Hero. + +```yaml +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue powered static site generator. + tagline: Lorem ipsum... + image: + src: /logo.png + alt: VitePress + actions: + - theme: brand + text: Get Started + link: /guide/what-is-vitepress + - theme: alt + text: View on GitHub + link: https://github.com/vuejs/vitepress +--- +``` + +```ts +interface Hero { + // String yang ditampilkan di atas `text`. Menggunakan warna brand + // dan diharapkan pendek, seperti nama produk. + name?: string + + // Teks utama untuk bagian hero. Ini akan didefinisikan + // sebagai tag `h1`. + text: string + + // Tagline yang ditampilkan di bawah `text`. + tagline?: string + + // Gambar ditampilkan di samping area teks dan tagline. + image?: ThemeableImage + + // Tombol aksi untuk ditampilkan di bagian hero beranda. + actions?: HeroAction[] +} + +type ThemeableImage = + | string + | { src: string; alt?: string } + | { light: string; dark: string; alt?: string } + +interface HeroAction { + // Tema warna tombol. Default ke `brand`. + theme?: 'brand' | 'alt' + + // Label tombol. + text: string + + // Tautan tujuan tombol. + link: string + + // Atribut target tautan. + target?: string + + // Atribut rel tautan. + rel?: string +} +``` + +### Menyesuaikan warna name + +VitePress menggunakan warna brand (`--vp-c-brand-1`) untuk `name`. Namun, Anda dapat menyesuaikan warna ini dengan menimpa variabel `--vp-home-hero-name-color`. + +```css +:root { + --vp-home-hero-name-color: blue; +} +``` + +Anda juga dapat menyesuaikannya lebih lanjut dengan menggabungkan `--vp-home-hero-name-background` untuk memberikan warna gradien pada `name`. + +```css +:root { + --vp-home-hero-name-color: transparent; + --vp-home-hero-name-background: -webkit-linear-gradient(120deg, #bd34fe, #41d1ff); +} +``` + +## Bagian Features + +Di bagian Features, Anda dapat mencantumkan sejumlah fitur yang ingin ditampilkan tepat setelah bagian Hero. Untuk mengonfigurasinya, berikan opsi `features` ke frontmatter. + +Anda dapat memberikan ikon untuk setiap fitur, yang dapat berupa emoji atau jenis gambar apa pun. Ketika ikon yang dikonfigurasi adalah gambar (svg, png, jpeg...), Anda harus memberikan ikon dengan lebar dan tinggi yang tepat; Anda juga dapat memberikan deskripsi, ukuran intrinsiknya serta varian untuk tema gelap dan terang jika diperlukan. + +```yaml +--- +layout: home + +features: + - icon: 🛠️ + title: Simple and minimal, always + details: Lorem ipsum... + - icon: + src: /cool-feature-icon.svg + title: Another cool feature + details: Lorem ipsum... + - icon: + dark: /dark-feature-icon.svg + light: /light-feature-icon.svg + title: Another cool feature + details: Lorem ipsum... +--- +``` + +```ts +interface Feature { + // Tampilkan ikon pada setiap kotak fitur. + icon?: FeatureIcon + + // Judul fitur. + title: string + + // Detail fitur. + details: string + + // Tautan ketika diklik pada komponen fitur. Tautan dapat + // berupa internal atau eksternal. + // + // mis. `guide/reference/default-theme-home-page` atau `https://example.com` + link?: string + + // Teks tautan yang akan ditampilkan di dalam komponen fitur. Paling baik + // digunakan dengan opsi `link`. + // + // mis. `Learn more`, `Visit page`, dll. + linkText?: string + + // Atribut rel tautan untuk opsi `link`. + // + // mis. `external` + rel?: string + + // Atribut target tautan untuk opsi `link`. + target?: string +} + +type FeatureIcon = + | string + | { src: string; alt?: string; width?: string; height: string } + | { + light: string + dark: string + alt?: string + width?: string + height: string + } +``` + +## Konten Markdown + +Anda dapat menambahkan konten tambahan ke beranda situs Anda hanya dengan menambahkan Markdown di bawah pembatas frontmatter `---`. + +````md +--- +layout: home + +hero: + name: VitePress + text: Vite & Vue powered static site generator. +--- + +## Memulai + +Anda dapat mulai menggunakan VitePress langsung menggunakan `npx`! + +```sh +npm init +npx vitepress init +``` +```` + +::: info +VitePress tidak selalu menata konten tambahan dari halaman `layout: home` secara otomatis. Untuk kembali ke perilaku lama, Anda dapat menambahkan `markdownStyles: false` ke frontmatter. +::: diff --git a/docs/id/reference/default-theme-last-updated.md b/docs/id/reference/default-theme-last-updated.md new file mode 100644 index 000000000..836f7c35e --- /dev/null +++ b/docs/id/reference/default-theme-last-updated.md @@ -0,0 +1,50 @@ +--- +description: Tampilkan timestamp terakhir diperbarui pada halaman VitePress berdasarkan riwayat commit Git. +--- + +# Last Updated + +Waktu pembaruan konten terakhir akan ditampilkan di sudut kanan bawah halaman. Untuk mengaktifkannya, tambahkan opsi `lastUpdated` ke config Anda. + +::: info +VitePress menampilkan waktu "last updated" menggunakan timestamp dari commit Git terbaru untuk setiap file. Untuk mengaktifkannya, file Markdown harus di-commit ke Git. + +Secara internal, VitePress menjalankan `git log -1 --pretty="%ai"` pada setiap file untuk mengambil timestamp-nya. Jika semua halaman menampilkan waktu pembaruan yang sama, kemungkinan besar disebabkan oleh shallow cloning (umum di lingkungan CI), yang membatasi riwayat Git. + +Untuk memperbaikinya di **GitHub Actions**, gunakan yang berikut dalam workflow Anda: + +```yaml{4} +- name: Checkout + uses: actions/checkout@v5 + with: + fetch-depth: 0 +``` + +Platform CI/CD lain memiliki pengaturan serupa. + +Jika opsi tersebut tidak tersedia, Anda dapat menambahkan perintah `docs:build` di `package.json` Anda dengan fetch manual: + +```json +"docs:build": "git fetch --unshallow && vitepress build docs" +``` +::: + +## Konfigurasi Tingkat Situs + +```js +export default { + lastUpdated: true +} +``` + +## Konfigurasi Frontmatter + +Ini dapat dinonaktifkan per halaman menggunakan opsi `lastUpdated` di frontmatter: + +```yaml +--- +lastUpdated: false +--- +``` + +Lihat juga [Default Theme: Last Updated](./default-theme-config#lastupdated) untuk detail lebih lanjut. Nilai truthy apa pun di tingkat tema juga akan mengaktifkan fitur ini kecuali dinonaktifkan secara eksplisit di tingkat situs atau halaman. diff --git a/docs/id/reference/default-theme-layout.md b/docs/id/reference/default-theme-layout.md new file mode 100644 index 000000000..0d9545f50 --- /dev/null +++ b/docs/id/reference/default-theme-layout.md @@ -0,0 +1,66 @@ +--- +description: Pilih antara layout doc, page, dan home di tema default VitePress. +--- + +# Layout + +Anda dapat memilih layout halaman dengan mengatur opsi `layout` di [frontmatter](./frontmatter-config) halaman. Tersedia 3 opsi layout, `doc`, `page`, dan `home`. Jika tidak ada yang ditentukan, maka halaman diperlakukan sebagai halaman `doc`. + +```yaml +--- +layout: doc +--- +``` + +## Layout Doc + +Opsi `doc` adalah layout default dan memberikan gaya pada seluruh konten Markdown menjadi tampilan "dokumentasi". Ini bekerja dengan membungkus seluruh konten dalam kelas css `vp-doc`, dan menerapkan gaya pada elemen-elemen di dalamnya. + +Hampir semua elemen generik seperti `p`, atau `h2` mendapatkan gaya khusus. Oleh karena itu, perlu diingat bahwa jika Anda menambahkan HTML kustom di dalam konten Markdown, elemen-elemen tersebut juga akan terpengaruh oleh gaya tersebut. + +Layout ini juga menyediakan fitur khusus dokumentasi yang tercantum di bawah. Fitur-fitur ini hanya diaktifkan di layout ini. + +- Edit Link +- Prev Next Link +- Outline +- [Carbon Ads](./default-theme-carbon-ads) + +## Layout Page + +Opsi `page` diperlakukan sebagai "halaman kosong". Markdown akan tetap di-parse, dan semua [Ekstensi Markdown](../guide/markdown) bekerja sama seperti layout `doc`, tetapi konten tidak mendapatkan gaya default apa pun. + +Dengan layout page, Anda dapat mengatur gaya semuanya sendiri tanpa tema VitePress memengaruhi markup. Ini berguna ketika Anda ingin membuat halaman kustom Anda sendiri. + +Perhatikan bahwa bahkan di layout ini, sidebar tetap akan muncul jika halaman memiliki konfigurasi sidebar yang cocok. + +## Layout Home + +Opsi `home` akan menghasilkan "Homepage" bertemplate. Dalam layout ini, Anda dapat mengatur opsi tambahan seperti `hero` dan `features` untuk menyesuaikan konten lebih lanjut. Kunjungi [Default Theme: Home Page](./default-theme-home-page) untuk detail lebih lanjut. + +## Tanpa Layout + +Jika Anda tidak menginginkan layout apa pun, Anda dapat mengirimkan `layout: false` melalui frontmatter. Opsi ini berguna jika Anda menginginkan landing page yang sepenuhnya dapat disesuaikan (tanpa sidebar, navbar, atau footer secara default). + +## Layout Kustom + +Anda juga dapat menggunakan layout kustom: + +```md +--- +layout: foo +--- +``` + +Ini akan mencari komponen bernama `foo` yang terdaftar dalam konteks. Misalnya, Anda dapat mendaftarkan komponen Anda secara global di `.vitepress/theme/index.ts`: + +```ts +import DefaultTheme from 'vitepress/theme' +import Foo from './Foo.vue' + +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + app.component('foo', Foo) + } +} +``` diff --git a/docs/id/reference/default-theme-nav.md b/docs/id/reference/default-theme-nav.md new file mode 100644 index 000000000..6d01a19c0 --- /dev/null +++ b/docs/id/reference/default-theme-nav.md @@ -0,0 +1,220 @@ +--- +description: Konfigurasikan bilah navigasi di tema default VitePress termasuk judul situs, logo, dan tautan menu. +--- + +# Nav + +Nav adalah bilah navigasi yang ditampilkan di bagian atas halaman. Ini berisi judul situs, tautan menu global, dan lain-lain. + +## Judul Situs dan Logo + +Secara default, nav menampilkan judul situs yang merujuk pada nilai [`config.title`](./site-config#title). Jika Anda ingin mengubah apa yang ditampilkan di nav, Anda dapat mendefinisikan teks kustom di opsi `themeConfig.siteTitle`. + +```js +export default { + themeConfig: { + siteTitle: 'My Custom Title' + } +} +``` + +Jika Anda memiliki logo untuk situs Anda, Anda dapat menampilkannya dengan memberikan path ke gambar. Anda sebaiknya menempatkan logo langsung di dalam `public`, dan mendefinisikan path absolut ke sana. + +```js +export default { + themeConfig: { + logo: '/my-logo.svg' + } +} +``` + +Ketika menambahkan logo, logo akan ditampilkan bersama dengan judul situs. Jika logo saja sudah cukup dan Anda ingin menyembunyikan teks judul situs, atur opsi `siteTitle` ke `false`. + +```js +export default { + themeConfig: { + logo: '/my-logo.svg', + siteTitle: false + } +} +``` + +Anda juga dapat memberikan objek sebagai logo jika ingin menambahkan atribut `alt` atau menyesuaikannya berdasarkan mode gelap/terang. Lihat [`themeConfig.logo`](./default-theme-config#logo) untuk detailnya. + +## Tautan Navigasi + +Anda dapat mendefinisikan opsi `themeConfig.nav` untuk menambahkan tautan ke nav Anda. + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { text: 'Config', link: '/config' }, + { text: 'Changelog', link: 'https://github.com/...' } + ] + } +} +``` + +`text` adalah teks aktual yang ditampilkan di nav, dan `link` adalah tautan yang akan dinavigasi ketika teks diklik. Untuk tautan, atur path ke file aktual tanpa awalan `.md`, dan selalu mulai dengan `/`. + +`link` juga dapat berupa fungsi yang menerima [`PageData`](./runtime-api#usedata) sebagai argumen dan mengembalikan path. + +Tautan nav juga dapat berupa menu dropdown. Untuk melakukan ini, atur kunci `items` pada opsi tautan. + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { text: 'Item A', link: '/item-1' }, + { text: 'Item B', link: '/item-2' }, + { text: 'Item C', link: '/item-3' } + ] + } + ] + } +} +``` + +Perhatikan bahwa judul menu dropdown (`Dropdown Menu` pada contoh di atas) tidak dapat memiliki properti `link` karena berfungsi sebagai tombol untuk membuka dialog dropdown. + +Anda juga dapat menambahkan "bagian" ke item menu dropdown dengan memberikan item bersarang lebih lanjut. + +```js +export default { + themeConfig: { + nav: [ + { text: 'Guide', link: '/guide' }, + { + text: 'Dropdown Menu', + items: [ + { + // Judul untuk bagian. + text: 'Section A Title', + items: [ + { text: 'Section A Item A', link: '...' }, + { text: 'Section B Item B', link: '...' } + ] + } + ] + }, + { + text: 'Dropdown Menu', + items: [ + { + // Anda juga dapat menghilangkan judul. + items: [ + { text: 'Section A Item A', link: '...' }, + { text: 'Section B Item B', link: '...' } + ] + } + ] + } + ] + } +} +``` + +### Menyesuaikan status "active" tautan + +Item menu nav akan disorot ketika halaman saat ini berada di bawah path yang cocok. Jika Anda ingin menyesuaikan path yang akan dicocokkan, definisikan properti `activeMatch` dan regex sebagai nilai string. + +```js +export default { + themeConfig: { + nav: [ + // Tautan ini mendapatkan status active ketika pengguna + // berada di path `/config/`. + { + text: 'Guide', + link: '/guide', + activeMatch: '/config/' + } + ] + } +} +``` + +::: warning +`activeMatch` diharapkan berupa string regex, tetapi Anda harus mendefinisikannya sebagai string. Kita tidak dapat menggunakan objek RegExp aktual di sini karena tidak dapat diserialisasi selama waktu build. +::: + +### Menyesuaikan atribut "target" dan "rel" tautan + +Secara default, VitePress secara otomatis menentukan atribut `target` dan `rel` berdasarkan apakah tautan tersebut merupakan tautan eksternal. Tetapi jika Anda mau, Anda juga dapat menyesuaikannya. + +```js +export default { + themeConfig: { + nav: [ + { + text: 'Merchandise', + link: 'https://www.thegithubshop.com/', + target: '_self', + rel: 'sponsored' + } + ] + } +} +``` + +## Tautan Sosial + +Lihat [`socialLinks`](./default-theme-config#sociallinks). + +## Komponen Kustom + +Anda dapat menyertakan komponen kustom di bilah navigasi dengan menggunakan opsi `component`. Kunci `component` harus berupa nama komponen Vue, dan harus didaftarkan secara global menggunakan [Theme.enhanceApp](../guide/custom-theme#theme-interface). + +```js [.vitepress/config.js] +export default { + themeConfig: { + nav: [ + { + text: 'My Menu', + items: [ + { + component: 'MyCustomComponent', + // Props opsional untuk diteruskan ke komponen + props: { + title: 'My Custom Component' + } + } + ] + }, + { + component: 'AnotherCustomComponent' + } + ] + } +} +``` + +Kemudian, Anda perlu mendaftarkan komponen secara global: + +```js [.vitepress/theme/index.js] +import DefaultTheme from 'vitepress/theme' + +import MyCustomComponent from './components/MyCustomComponent.vue' +import AnotherCustomComponent from './components/AnotherCustomComponent.vue' + +/** @type {import('vitepress').Theme} */ +export default { + extends: DefaultTheme, + enhanceApp({ app }) { + app.component('MyCustomComponent', MyCustomComponent) + app.component('AnotherCustomComponent', AnotherCustomComponent) + } +} +``` + +Komponen Anda akan dirender di bilah navigasi. VitePress akan memberikan props tambahan berikut ke komponen: + +- `screenMenu`: boolean opsional yang menunjukkan apakah komponen berada di dalam menu navigasi mobile + +Anda dapat melihat contoh di e2e tests [di sini](https://github.com/vuejs/vitepress/tree/main/__tests__/e2e/.vitepress). diff --git a/docs/id/reference/default-theme-prev-next-links.md b/docs/id/reference/default-theme-prev-next-links.md new file mode 100644 index 000000000..2be22565e --- /dev/null +++ b/docs/id/reference/default-theme-prev-next-links.md @@ -0,0 +1,47 @@ +--- +description: Sesuaikan tautan halaman sebelumnya dan berikutnya yang ditampilkan di bagian bawah halaman dokumen di VitePress. +--- + +# Prev Next Links + +Anda dapat menyesuaikan teks dan tautan untuk halaman sebelumnya dan berikutnya (ditampilkan di footer dokumen). Ini berguna jika Anda menginginkan teks yang berbeda dari yang ada di sidebar. Selain itu, Anda mungkin merasa berguna untuk menonaktifkan footer atau menautkan ke halaman yang tidak termasuk dalam sidebar Anda. + +## prev + +- Tipe: `string | false | { text?: string; link?: string }` + +- Detail: + + Menentukan teks/tautan yang akan ditampilkan pada tautan ke halaman sebelumnya. Jika Anda tidak mengatur ini di frontmatter, teks/tautan akan disimpulkan dari konfigurasi sidebar. + +- Contoh: + + - Untuk menyesuaikan hanya teks: + + ```yaml + --- + prev: 'Memulai | Markdown' + --- + ``` + + - Untuk menyesuaikan teks dan tautan: + + ```yaml + --- + prev: + text: 'Markdown' + link: '/guide/markdown' + --- + ``` + + - Untuk menyembunyikan halaman sebelumnya: + + ```yaml + --- + prev: false + --- + ``` + +## next + +Sama seperti `prev` tetapi untuk halaman berikutnya. diff --git a/docs/id/reference/default-theme-search.md b/docs/id/reference/default-theme-search.md new file mode 100644 index 000000000..68b99ac0c --- /dev/null +++ b/docs/id/reference/default-theme-search.md @@ -0,0 +1,360 @@ +--- +outline: deep +description: Siapkan pencarian lokal atau berbasis Algolia untuk situs VitePress Anda. +--- + +# Pencarian + +## Pencarian Lokal + +VitePress mendukung pencarian teks lengkap fuzzy menggunakan indeks dalam browser berkat [minisearch](https://github.com/lucaong/minisearch/). Untuk mengaktifkan fitur ini, cukup atur opsi `themeConfig.search.provider` ke `'local'` di file `.vitepress/config.ts` Anda: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local' + } + } +}) +``` + +Contoh hasil: + +![screenshot of the search modal](/search.png) + +Sebagai alternatif, Anda dapat menggunakan [Algolia DocSearch](#algolia-search) atau beberapa plugin komunitas seperti: + +- +- +- +- + +### i18n {#local-search-i18n} + +Anda dapat menggunakan konfigurasi seperti ini untuk menggunakan pencarian multibahasa: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + locales: { + zh: { // gunakan `root` jika Anda ingin menerjemahkan locale default + translations: { + button: { + buttonText: '搜索', + buttonAriaLabel: '搜索' + }, + modal: { + displayDetails: '显示详细列表', + resetButtonTitle: '重置搜索', + backButtonTitle: '关闭搜索', + noResultsText: '没有结果', + footer: { + selectText: '选择', + selectKeyAriaLabel: '输入', + navigateText: '导航', + navigateUpKeyAriaLabel: '上箭头', + navigateDownKeyAriaLabel: '下箭头', + closeText: '关闭', + closeKeyAriaLabel: 'esc' + } + } + } + } + } + } + } + } +}) +``` + +### Opsi miniSearch + +Anda dapat mengonfigurasi MiniSearch seperti ini: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + miniSearch: { + /** + * @type {Pick} + */ + options: { + /* ... */ + }, + /** + * @type {import('minisearch').SearchOptions} + * @default + * { fuzzy: 0.2, prefix: true, boost: { title: 4, text: 2, titles: 1 } } + */ + searchOptions: { + /* ... */ + } + } + } + } + } +}) +``` + +Pelajari lebih lanjut di [dokumentasi MiniSearch](https://lucaong.github.io/minisearch/classes/MiniSearch.MiniSearch.html). + +### Perender konten kustom + +Anda dapat menyesuaikan fungsi yang digunakan untuk merender konten markdown sebelum mengindeksnya: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + /** + * @param {string} src + * @param {import('vitepress').MarkdownEnv} env + * @param {import('markdown-it-async')} md + */ + async _render(src, env, md) { + // kembalikan string html + } + } + } + } +}) +``` + +Fungsi ini akan dihapus dari data situs sisi klien, sehingga Anda dapat menggunakan API Node.js di dalamnya. + +#### Contoh: Mengecualikan halaman dari pencarian + +Anda dapat mengecualikan halaman dari pencarian dengan menambahkan `search: false` ke frontmatter halaman. Sebagai alternatif: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + async _render(src, env, md) { + const html = await md.renderAsync(src, env) + if (env.frontmatter?.search === false) return '' + if (env.relativePath.startsWith('some/path')) return '' + return html + } + } + } + } +}) +``` + +::: warning Catatan +Jika fungsi `_render` kustom disediakan, Anda perlu menangani sendiri `search: false` di frontmatter. Selain itu, objek `env` tidak akan sepenuhnya terisi sebelum `md.renderAsync` dipanggil, jadi pemeriksaan apa pun pada properti opsional `env` seperti `frontmatter` harus dilakukan setelahnya. +::: + +#### Contoh: Mentransformasi konten - menambahkan anchor + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'local', + options: { + async _render(src, env, md) { + const html = await md.renderAsync(src, env) + if (env.frontmatter?.title) + return (await md.renderAsync(`# ${env.frontmatter.title}`)) + html + return html + } + } + } + } +}) +``` + +## Pencarian Algolia + +VitePress mendukung pencarian di situs dokumentasi Anda menggunakan [Algolia DocSearch](https://docsearch.algolia.com/docs/what-is-docsearch). Lihat panduan memulai mereka. Di `.vitepress/config.ts` Anda, setidaknya Anda perlu menyediakan yang berikut agar berfungsi: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...' + } + } + } +}) +``` + +### i18n {#algolia-search-i18n} + +Anda dapat menggunakan konfigurasi seperti ini untuk menggunakan pencarian multibahasa: + +

+Lihat contoh lengkap + +<<< @/snippets/algolia-i18n.ts + +
+ +Lihat [dokumentasi resmi Algolia](https://docsearch.algolia.com/docs/api#translations) untuk mempelajari lebih lanjut. Untuk memulai dengan cepat, Anda juga dapat menyalin terjemahan yang digunakan oleh situs ini dari [repo GitHub kami](https://github.com/search?q=repo:vuejs/vitepress+%22function+searchOptions%22&type=code). + +### Dukungan Algolia Ask AI {#ask-ai} + +Jika Anda ingin menyertakan **Ask AI**, berikan opsi `askAi` (atau salah satu field parsial) di dalam `options`: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...', + // askAi: "YOUR-ASSISTANT-ID" + // ATAU + askAi: { + // minimal Anda harus memberikan assistantId yang Anda terima dari Algolia + assistantId: 'XXXYYY', + // penimpaan opsional – jika dihilangkan, nilai appId/apiKey/indexName tingkat atas digunakan kembali + // apiKey: '...', + // appId: '...', + // indexName: '...' + } + } + } + } +}) +``` + +::: warning Catatan +Jika Anda ingin default ke pencarian keyword dan tidak ingin menggunakan Ask AI, hilangkan properti `askAi`. +::: + +### Panel Samping Ask AI {#ask-ai-side-panel} + +DocSearch v4.5+ mendukung **panel samping Ask AI** opsional. Ketika diaktifkan, panel ini dapat dibuka dengan **Ctrl/Cmd+I** secara default. [Referensi API Sidepanel](https://docsearch.algolia.com/docs/sidepanel/api-reference) berisi daftar opsi lengkap. + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...', + askAi: { + assistantId: 'XXXYYY', + sidePanel: { + panel: { + variant: 'floating', // atau 'inline' + side: 'right', + width: '360px', + expandedWidth: '580px', + suggestedQuestions: true + } + } + } + } + } + } +}) +``` + +Jika Anda perlu menonaktifkan shortcut keyboard, gunakan opsi `keyboardShortcuts` di tingkat root sidepanel: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + appId: '...', + apiKey: '...', + indexName: '...', + askAi: { + assistantId: 'XXXYYY', + sidePanel: { + keyboardShortcuts: { + 'Ctrl/Cmd+I': false + } + } + } + } + } + } +}) +``` + +#### Mode (auto / sidePanel / hybrid / modal) {#ask-ai-mode} + +Anda dapat secara opsional mengontrol bagaimana VitePress mengintegrasikan pencarian keyword dan Ask AI: + +- `mode: 'auto'` (default): menyimpulkan `hybrid` ketika pencarian keyword dikonfigurasi, jika tidak `sidePanel` ketika panel samping Ask AI dikonfigurasi. +- `mode: 'sidePanel'`: paksa hanya panel samping (menyembunyikan tombol pencarian keyword). +- `mode: 'hybrid'`: aktifkan modal pencarian keyword + panel samping Ask AI (memerlukan konfigurasi pencarian keyword). +- `mode: 'modal'`: pertahankan Ask AI di dalam modal DocSearch (bahkan jika Anda mengonfigurasi panel samping). + +#### Hanya Ask AI (tanpa pencarian keyword) {#ask-ai-only} + +Jika Anda ingin menggunakan **panel samping Ask AI saja**, Anda dapat menghilangkan konfigurasi pencarian keyword tingkat atas dan memberikan kredensial di bawah `askAi`: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + search: { + provider: 'algolia', + options: { + mode: 'sidePanel', + askAi: { + assistantId: 'XXXYYY', + appId: '...', + apiKey: '...', + indexName: '...', + sidePanel: true + } + } + } + } +}) +``` + +### Konfigurasi Crawler + +Berikut adalah contoh konfigurasi berdasarkan apa yang digunakan situs ini: + +<<< @/snippets/algolia-crawler.js diff --git a/docs/id/reference/default-theme-sidebar.md b/docs/id/reference/default-theme-sidebar.md new file mode 100644 index 000000000..0ad61d83c --- /dev/null +++ b/docs/id/reference/default-theme-sidebar.md @@ -0,0 +1,186 @@ +--- +description: Konfigurasikan navigasi sidebar di tema default VitePress dengan grup, bagian yang dapat diciutkan, dan multiple sidebar. +--- + +# Sidebar + +Sidebar adalah blok navigasi utama untuk dokumentasi Anda. Anda dapat mengonfigurasi menu sidebar di [`themeConfig.sidebar`](./default-theme-config#sidebar). + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + { text: 'Introduction', link: '/introduction' }, + { text: 'Getting Started', link: '/getting-started' }, + ... + ] + } + ] + } +} +``` + +## Dasar-dasar + +Bentuk paling sederhana dari menu sidebar adalah dengan memberikan array tunggal tautan. Item level pertama mendefinisikan "bagian" untuk sidebar. Ini harus berisi `text`, yang merupakan judul bagian, dan `items` yang merupakan tautan navigasi aktual. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + items: [ + { text: 'Item A', link: '/item-a' }, + { text: 'Item B', link: '/item-b' }, + ... + ] + }, + { + text: 'Section Title B', + items: [ + { text: 'Item C', link: '/item-c' }, + { text: 'Item D', link: '/item-d' }, + ... + ] + } + ] + } +} +``` + +Setiap `link` harus menentukan path ke file aktual dimulai dengan `/`. Jika Anda menambahkan trailing slash di akhir tautan, itu akan menampilkan `index.md` dari direktori terkait. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Guide', + items: [ + // Ini menampilkan halaman `/guide/index.md`. + { text: 'Introduction', link: '/guide/' } + ] + } + ] + } +} +``` + +Anda dapat menyarangkan item sidebar hingga sedalam 6 level dihitung dari level root. Perhatikan bahwa item bersarang lebih dalam dari 6 level akan diabaikan dan tidak akan ditampilkan di sidebar. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Level 1', + items: [ + { + text: 'Level 2', + items: [ + { + text: 'Level 3', + items: [ + ... + ] + } + ] + } + ] + } + ] + } +} +``` + +## Multiple Sidebar + +Anda dapat menampilkan sidebar yang berbeda tergantung pada path halaman. Misalnya, seperti yang ditunjukkan di situs ini, Anda mungkin ingin membuat bagian konten terpisah dalam dokumentasi Anda seperti halaman "Guide" dan halaman "Config". + +Untuk melakukannya, pertama atur halaman Anda ke dalam direktori untuk setiap bagian yang diinginkan: + +``` +. +├─ guide/ +│ ├─ index.md +│ ├─ one.md +│ └─ two.md +└─ config/ + ├─ index.md + ├─ three.md + └─ four.md +``` + +Kemudian, perbarui konfigurasi Anda untuk mendefinisikan sidebar untuk setiap bagian. Kali ini, Anda harus memberikan objek, bukan array. + +```js +export default { + themeConfig: { + sidebar: { + // Sidebar ini ditampilkan ketika pengguna + // berada di direktori `guide`. + '/guide/': [ + { + text: 'Guide', + items: [ + { text: 'Index', link: '/guide/' }, + { text: 'One', link: '/guide/one' }, + { text: 'Two', link: '/guide/two' } + ] + } + ], + + // Sidebar ini ditampilkan ketika pengguna + // berada di direktori `config`. + '/config/': [ + { + text: 'Config', + items: [ + { text: 'Index', link: '/config/' }, + { text: 'Three', link: '/config/three' }, + { text: 'Four', link: '/config/four' } + ] + } + ] + } + } +} +``` + +## Grup Sidebar yang Dapat Diciutkan + +Dengan menambahkan opsi `collapsed` ke grup sidebar, ini menampilkan tombol toggle untuk menyembunyikan/menampilkan setiap bagian. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + collapsed: false, + items: [...] + } + ] + } +} +``` + +Semua bagian "terbuka" secara default. Jika Anda menginginkannya "tertutup" saat halaman pertama dimuat, atur opsi `collapsed` ke `true`. + +```js +export default { + themeConfig: { + sidebar: [ + { + text: 'Section Title A', + collapsed: true, + items: [...] + } + ] + } +} +``` diff --git a/docs/id/reference/default-theme-team-page.md b/docs/id/reference/default-theme-team-page.md new file mode 100644 index 000000000..9d427883d --- /dev/null +++ b/docs/id/reference/default-theme-team-page.md @@ -0,0 +1,260 @@ +--- +description: Buat halaman tim dengan profil anggota menggunakan komponen tim bawaan VitePress. +--- + + + +# Halaman Tim + +Jika Anda ingin memperkenalkan tim Anda, Anda dapat menggunakan komponen Team untuk membuat Halaman Tim. Ada dua cara menggunakan komponen ini. Salah satunya adalah menyematkannya di halaman dokumen, dan yang lainnya adalah membuat Halaman Tim penuh. + +## Menampilkan anggota tim di sebuah halaman + +Anda dapat menggunakan komponen `` yang diekspos dari `vitepress/theme` untuk menampilkan daftar anggota tim di halaman mana pun. + +```html + + +# Tim Kami + +Sapa tim hebat kami. + + +``` + +Di atas akan menampilkan anggota tim dalam elemen bergaya kartu. Seharusnya menampilkan sesuatu yang mirip dengan di bawah ini. + + + +Komponen `` tersedia dalam 2 ukuran berbeda, `small` dan `medium`. Meskipun tergantung pada preferensi Anda, biasanya ukuran `small` lebih cocok ketika digunakan di halaman dokumen. Anda juga dapat menambahkan lebih banyak properti ke setiap anggota seperti menambahkan tombol "description" atau "sponsor". Pelajari lebih lanjut di [``](#vpteammembers). + +Menyematkan anggota tim di halaman dokumen cocok untuk tim berukuran kecil di mana memiliki halaman tim penuh khusus mungkin terlalu berlebihan, atau memperkenalkan sebagian anggota sebagai referensi untuk konteks dokumentasi. + +Jika Anda memiliki jumlah anggota yang banyak, atau hanya ingin memiliki lebih banyak ruang untuk menampilkan anggota tim, pertimbangkan untuk [membuat halaman tim penuh](#create-a-full-team-page). + +## Membuat Halaman Tim Penuh + +Alih-alih menambahkan anggota tim ke halaman dokumen, Anda juga dapat membuat Halaman Tim penuh, mirip dengan cara Anda membuat [Home Page](./default-theme-home-page) kustom. + +Untuk membuat halaman tim, pertama, buat file md baru. Nama file tidak masalah, tetapi di sini kita sebut saja `team.md`. Di file ini, atur opsi frontmatter `layout: page`, lalu Anda dapat menyusun struktur halaman Anda menggunakan komponen `TeamPage`. + +```html +--- +layout: page +--- + + + + + + + + + +``` + +Ketika membuat halaman tim penuh, ingatlah untuk membungkus semua komponen dengan komponen ``. Komponen ini akan memastikan semua komponen terkait tim yang bersarang mendapatkan struktur layout yang tepat seperti spasi. + +Komponen `` menambahkan bagian judul halaman. Judul berupa heading `

`. Gunakan slot `#title` dan `#lead` untuk mendokumentasikan tentang tim Anda. + +`` bekerja sama seperti ketika digunakan di halaman dokumen. Ini akan menampilkan daftar anggota. + +### Menambahkan bagian untuk membagi anggota tim + +Anda dapat menambahkan "bagian" ke halaman tim. Misalnya, Anda mungkin memiliki berbagai jenis anggota tim seperti Anggota Tim Inti dan Mitra Komunitas. Anda dapat membagi anggota-anggota ini menjadi beberapa bagian untuk menjelaskan peran masing-masing grup dengan lebih baik. + +Untuk melakukannya, tambahkan komponen `` ke file `team.md` yang kita buat sebelumnya. + +```html +--- +layout: page +--- + + + + + + + + + + + + + + +``` + +Komponen `` dapat memiliki slot `#title` dan `#lead` mirip dengan komponen `VPTeamPageTitle`, dan juga slot `#members` untuk menampilkan anggota tim. + +Ingatlah untuk menempatkan komponen `` di dalam slot `#members`. + +## `` + +Komponen `` menampilkan daftar anggota yang diberikan. + +```html + +``` + +```ts +interface Props { + // Ukuran setiap anggota. Default ke `medium`. + size?: 'small' | 'medium' + + // Daftar anggota yang akan ditampilkan. + members: TeamMember[] +} + +interface TeamMember { + // Gambar avatar untuk anggota. + avatar: string + + // Nama anggota. + name: string + + // Judul yang akan ditampilkan di bawah nama anggota. + // mis. Developer, Software Engineer, dll. + title?: string + + // Organisasi tempat anggota bernaung. + org?: string + + // URL untuk organisasi. + orgLink?: string + + // Deskripsi untuk anggota. + desc?: string + + // Tautan sosial. mis. GitHub, Twitter, dll. Anda dapat memberikan + // objek Social Links di sini. + // Lihat: https://vitepress.dev/reference/default-theme-config.html#sociallinks + links?: SocialLink[] + + // URL untuk halaman sponsor anggota. + sponsor?: string + + // Teks untuk tautan sponsor. Default ke 'Sponsor'. + actionText?: string +} +``` + +## `` + +Komponen root ketika membuat halaman tim penuh. Ini hanya menerima satu slot. Ini akan menata semua komponen terkait tim yang diberikan. + +## `` + +Menambahkan bagian "judul" halaman. Paling baik digunakan di bagian paling awal di bawah ``. Ini menerima slot `#title` dan `#lead`. + +```html + + + + + + +``` + +## `` + +Membuat "bagian" di dalam halaman tim. Ini menerima slot `#title`, `#lead`, dan `#members`. Anda dapat menambahkan bagian sebanyak yang Anda suka di dalam ``. + +```html + + ... + + + + + + +``` diff --git a/docs/id/reference/frontmatter-config.md b/docs/id/reference/frontmatter-config.md new file mode 100644 index 000000000..32aa6caa4 --- /dev/null +++ b/docs/id/reference/frontmatter-config.md @@ -0,0 +1,241 @@ +--- +outline: deep +description: Referensi semua opsi konfigurasi frontmatter yang tersedia untuk halaman Markdown VitePress. +--- + +# Konfigurasi Frontmatter + +Frontmatter mengaktifkan konfigurasi berbasis halaman. Di setiap file markdown, Anda dapat menggunakan konfigurasi frontmatter untuk menimpa opsi konfigurasi tingkat situs atau tingkat tema. Selain itu, ada opsi konfigurasi yang hanya dapat Anda definisikan di frontmatter. + +Contoh penggunaan: + +```md +--- +title: Docs with VitePress +editLink: true +--- +``` + +Anda dapat mengakses data frontmatter melalui global `$frontmatter` dalam ekspresi Vue: + +```md +{{ $frontmatter.title }} +``` + +## title + +- Tipe: `string` + +Judul untuk halaman. Sama dengan [config.title](./site-config#title), dan ini menimpa konfigurasi tingkat situs. + +```yaml +--- +title: VitePress +--- +``` + +## titleTemplate + +- Tipe: `string | boolean` + +Sufiks untuk judul. Sama dengan [config.titleTemplate](./site-config#titletemplate), dan ini menimpa konfigurasi tingkat situs. + +```yaml +--- +title: VitePress +titleTemplate: Vite & Vue powered static site generator +--- +``` + +## description + +- Tipe: `string` + +Deskripsi untuk halaman. Sama dengan [config.description](./site-config#description), dan ini menimpa konfigurasi tingkat situs. + +```yaml +--- +description: VitePress +--- +``` + +## head + +- Tipe: `HeadConfig[]` + +Menentukan tag head tambahan untuk disuntikkan untuk halaman saat ini. Akan ditambahkan setelah tag head yang disuntikkan oleh konfigurasi tingkat situs. + +```yaml +--- +head: + - - meta + - name: description + content: hello + - - meta + - name: keywords + content: super duper SEO +--- +``` + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +## Hanya Tema Default + +Opsi frontmatter berikut hanya berlaku ketika menggunakan tema default. + +### layout + +- Tipe: `doc | home | page` +- Default: `doc` + +Menentukan layout halaman. + +- `doc` - Menerapkan gaya dokumentasi default ke konten markdown. +- `home` - Layout khusus untuk "Home Page". Anda dapat menambahkan opsi tambahan seperti `hero` dan `features` untuk membuat landing page yang indah dengan cepat. +- `page` - Berperilaku mirip dengan `doc` tetapi tidak menerapkan gaya apa pun ke konten. Berguna ketika Anda ingin membuat halaman yang sepenuhnya kustom. + +```yaml +--- +layout: doc +--- +``` + +### hero + +Mendefinisikan konten bagian hero beranda ketika `layout` diatur ke `home`. Detail lebih lanjut di [Default Theme: Home Page](./default-theme-home-page). + +### features + +Mendefinisikan item untuk ditampilkan di bagian features ketika `layout` diatur ke `home`. Detail lebih lanjut di [Default Theme: Home Page](./default-theme-home-page). + +### navbar + +- Tipe: `boolean` +- Default: `true` + +Apakah akan menampilkan [navbar](./default-theme-nav). + +```yaml +--- +navbar: false +--- +``` + +### sidebar + +- Tipe: `boolean` +- Default: `true` + +Apakah akan menampilkan [sidebar](./default-theme-sidebar). + +```yaml +--- +sidebar: false +--- +``` + +### aside + +- Tipe: `boolean | 'left'` +- Default: `true` + +Mendefinisikan lokasi komponen aside di layout `doc`. + +Mengatur nilai ini ke `false` mencegah rendering kontainer aside.\ +Mengatur nilai ini ke `true` merender aside di sebelah kanan.\ +Mengatur nilai ini ke `'left'` merender aside di sebelah kiri. + +```yaml +--- +aside: false +--- +``` + +### outline + +- Tipe: `number | [number, number] | 'deep' | false` +- Default: `2` + +Level heading di outline yang akan ditampilkan untuk halaman. Sama dengan [config.themeConfig.outline.level](./default-theme-config#outline), dan ini menimpa nilai yang diatur di konfigurasi tingkat situs. + +```yaml +--- +outline: [2, 4] +--- +``` + +### lastUpdated + +- Tipe: `boolean | Date` +- Default: `true` + +Apakah akan menampilkan teks [last updated](./default-theme-last-updated) di footer halaman saat ini. Jika datetime ditentukan, itu akan ditampilkan alih-alih timestamp git yang terakhir dimodifikasi. + +```yaml +--- +lastUpdated: false +--- +``` + +### editLink + +- Tipe: `boolean` +- Default: `true` + +Apakah akan menampilkan [edit link](./default-theme-edit-link) di footer halaman saat ini. + +```yaml +--- +editLink: false +--- +``` + +### footer + +- Tipe: `boolean` +- Default: `true` + +Apakah akan menampilkan [footer](./default-theme-footer). + +```yaml +--- +footer: false +--- +``` + +### pageClass + +- Tipe: `string` + +Menambahkan nama kelas tambahan ke halaman tertentu. + +```yaml +--- +pageClass: custom-page-class +--- +``` + +Kemudian Anda dapat menyesuaikan gaya halaman tertentu ini di file `.vitepress/theme/custom.css`: + +```css +.custom-page-class { + /* gaya khusus halaman */ +} +``` + +### isHome + +- Tipe: `boolean` + +Tema default mengandalkan pemeriksaan seperti `frontmatter.layout === 'home'` untuk menentukan apakah halaman saat ini adalah halaman beranda.\ +Ini berguna ketika Anda ingin memaksa menampilkan elemen halaman beranda di layout kustom. + +```yaml +--- +isHome: true +--- +``` diff --git a/docs/id/reference/runtime-api.md b/docs/id/reference/runtime-api.md new file mode 100644 index 000000000..0a92b2b65 --- /dev/null +++ b/docs/id/reference/runtime-api.md @@ -0,0 +1,177 @@ +--- +description: Referensi API runtime VitePress termasuk composable, fungsi helper, dan komponen bawaan. +--- + +# Runtime API + +VitePress menawarkan beberapa API bawaan untuk mengakses data aplikasi. VitePress juga dilengkapi dengan beberapa komponen bawaan yang dapat digunakan secara global. + +Metode helper dapat diimpor secara global dari `vitepress` dan biasanya digunakan dalam komponen Vue tema kustom. Namun, metode ini juga dapat digunakan di dalam halaman `.md` karena file markdown dikompilasi menjadi [Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html) Vue. + +Metode yang dimulai dengan `use*` menunjukkan bahwa itu adalah fungsi [Vue 3 Composition API](https://vuejs.org/guide/introduction.html#composition-api) ("Composable") yang hanya dapat digunakan di dalam `setup()` atau ` + + +``` + +## `useRoute` + +Mengembalikan objek rute saat ini dengan tipe berikut: + +```ts +interface Route { + path: string + data: PageData + component: Component | null +} +``` + +## `useRouter` + +Mengembalikan instance router VitePress sehingga Anda dapat bernavigasi ke halaman lain secara terprogram. + +```ts +interface Router { + /** + * Rute saat ini. + */ + route: Route + /** + * Navigasi ke URL baru. + */ + go: (to?: string) => Promise + /** + * Dipanggil sebelum rute berubah. Kembalikan `false` untuk membatalkan navigasi. + */ + onBeforeRouteChange?: (to: string) => Awaitable + /** + * Dipanggil sebelum komponen halaman dimuat (setelah state riwayat diperbarui). + * Kembalikan `false` untuk membatalkan navigasi. + */ + onBeforePageLoad?: (to: string) => Awaitable + /** + * Dipanggil setelah komponen halaman dimuat (sebelum komponen halaman diperbarui). + */ + onAfterPageLoad?: (to: string) => Awaitable + /** + * Dipanggil setelah rute berubah. + */ + onAfterRouteChange?: (to: string) => Awaitable +} +``` + +## `withBase` + +- **Tipe**: `(path: string) => string` + +Menambahkan [`base`](./site-config#base) yang dikonfigurasi ke path URL yang diberikan. Lihat juga [Base URL](../guide/asset-handling#base-url). + +## `` + +Komponen `` menampilkan konten markdown yang dirender. Berguna [ketika membuat tema Anda sendiri](../guide/custom-theme). + +```vue + +``` + +## `` + +Komponen `` merender slot-nya hanya di sisi klien. + +Karena aplikasi VitePress dirender di server dalam Node.js ketika menghasilkan build statis, penggunaan Vue apa pun harus mematuhi persyaratan kode universal. Singkatnya, pastikan hanya mengakses API Browser / DOM di hook beforeMount atau mounted. + +Jika Anda menggunakan atau mendemokan komponen yang tidak SSR-friendly (misalnya, berisi custom directives), Anda dapat membungkusnya di dalam komponen `ClientOnly`. + +```vue-html + + + +``` + +- Terkait: [SSR Compatibility](../guide/ssr-compat) + +## `$frontmatter` + +Langsung mengakses data [frontmatter](../guide/frontmatter) halaman saat ini dalam ekspresi Vue. + +```md +--- +title: Hello +--- + +# {{ $frontmatter.title }} +``` + +## `$params` + +Langsung mengakses [parameter rute dinamis](../guide/routing#dynamic-routes) halaman saat ini dalam ekspresi Vue. + +```md +- package name: {{ $params.pkg }} +- version: {{ $params.version }} +``` diff --git a/docs/id/reference/site-config.md b/docs/id/reference/site-config.md new file mode 100644 index 000000000..e1140ff24 --- /dev/null +++ b/docs/id/reference/site-config.md @@ -0,0 +1,753 @@ +--- +outline: deep +description: Referensi lengkap opsi konfigurasi situs VitePress termasuk pengaturan tingkat aplikasi, tema, dan opsi build. +--- + +# Konfigurasi Situs + +Konfigurasi situs adalah tempat Anda dapat mendefinisikan pengaturan global situs. Opsi konfigurasi aplikasi mendefinisikan pengaturan yang berlaku untuk setiap situs VitePress, terlepas dari tema apa yang digunakannya. Misalnya, direktori dasar atau judul situs. + +## Ringkasan + +### Resolusi Config + +File config selalu di-resolve dari `/.vitepress/config.[ext]`, di mana `` adalah [root proyek](../guide/routing#root-and-source-directory) VitePress Anda, dan `[ext]` adalah salah satu ekstensi file yang didukung. TypeScript didukung secara bawaan. Ekstensi yang didukung meliputi `.js`, `.ts`, `.mjs`, dan `.mts`. + +Disarankan untuk menggunakan sintaks modul ES di file config. File config harus mengekspor default sebuah objek: + +```ts +export default { + // opsi config tingkat aplikasi + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + ... +} +``` + +::: details Config Dinamis (Async) + +Jika Anda perlu menghasilkan config secara dinamis, Anda juga dapat mengekspor default sebuah fungsi. Misalnya: + +```ts +import { defineConfig } from 'vitepress' + +export default async () => { + const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + + return defineConfig({ + // opsi config tingkat aplikasi + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // opsi config tingkat tema + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } + }) +} +``` + +Anda juga dapat menggunakan `await` tingkat atas. Misalnya: + +```ts +import { defineConfig } from 'vitepress' + +const posts = await (await fetch('https://my-cms.com/blog-posts')).json() + +export default defineConfig({ + // opsi config tingkat aplikasi + lang: 'en-US', + title: 'VitePress', + description: 'Vite & Vue powered static site generator.', + + // opsi config tingkat tema + themeConfig: { + sidebar: [ + ...posts.map((post) => ({ + text: post.name, + link: `/posts/${post.name}` + })) + ] + } +}) +``` + +::: + +### Intellisense Config + +Menggunakan helper `defineConfig` akan memberikan intellisense berbasis TypeScript untuk opsi config. Dengan asumsi IDE Anda mendukungnya, ini seharusnya berfungsi di JavaScript dan TypeScript. + +```js +import { defineConfig } from 'vitepress' + +export default defineConfig({ + // ... +}) +``` + +### Konfigurasi Tema Bertipe + +Secara default, helper `defineConfig` mengharapkan tipe config tema dari tema default: + +```ts +import { defineConfig } from 'vitepress' + +export default defineConfig({ + themeConfig: { + // Tipe adalah `DefaultTheme.Config` + } +}) +``` + +Jika Anda menggunakan tema kustom dan menginginkan pengecekan tipe untuk config tema, Anda perlu menggunakan `defineConfigWithTheme`, dan mengirimkan tipe config untuk tema kustom Anda melalui argumen generik: + +```ts +import { defineConfigWithTheme } from 'vitepress' +import type { ThemeConfig } from 'your-theme' + +export default defineConfigWithTheme({ + themeConfig: { + // Tipe adalah `ThemeConfig` + } +}) +``` + +### Konfigurasi Vite, Vue, dan Markdown + +- **Vite** + + Anda dapat mengonfigurasi instance Vite yang mendasarinya menggunakan opsi [vite](#vite) di config VitePress Anda. Tidak perlu membuat file config Vite terpisah. + +- **Vue** + + VitePress sudah menyertakan plugin Vue resmi untuk Vite ([@vitejs/plugin-vue](https://github.com/vitejs/vite-plugin-vue)). Anda dapat mengonfigurasi opsinya menggunakan opsi [vue](#vue) di config VitePress Anda. + +- **Markdown** + + Anda dapat mengonfigurasi instance [Markdown-It](https://github.com/markdown-it/markdown-it) yang mendasarinya menggunakan opsi [markdown](#markdown) di config VitePress Anda. + +## Metadata Situs + +### title + +- Tipe: `string` +- Default: `VitePress` +- Dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#title) + +Judul untuk situs. Ketika menggunakan tema default, ini akan ditampilkan di bilah nav. + +Ini juga akan digunakan sebagai sufiks default untuk semua judul halaman individual, kecuali [`titleTemplate`](#titletemplate) didefinisikan. Judul akhir halaman individual akan berupa konten teks dari header `

` pertamanya, digabungkan dengan `title` global sebagai sufiks. Misalnya dengan config dan konten halaman berikut: + +```ts +export default { + title: 'My Awesome Site' +} +``` + +```md +# Hello +``` + +Judul halaman akan menjadi `Hello | My Awesome Site`. + +### titleTemplate + +- Tipe: `string | boolean` +- Dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#titletemplate) + +Memungkinkan penyesuaian sufiks judul setiap halaman atau seluruh judul. Misalnya: + +```ts +export default { + title: 'My Awesome Site', + titleTemplate: 'Custom Suffix' +} +``` + +```md +# Hello +``` + +Judul halaman akan menjadi `Hello | Custom Suffix`. + +Untuk sepenuhnya menyesuaikan bagaimana judul harus dirender, Anda dapat menggunakan simbol `:title` di `titleTemplate`: + +```ts +export default { + titleTemplate: ':title - Custom Suffix' +} +``` + +Di sini `:title` akan diganti dengan teks yang disimpulkan dari header `

` pertama halaman. Judul halaman contoh sebelumnya akan menjadi `Hello - Custom Suffix`. + +Opsi ini dapat diatur ke `false` untuk menonaktifkan sufiks judul. + +### description + +- Tipe: `string` +- Default: `A VitePress site` +- Dapat ditimpa per halaman melalui [frontmatter](./frontmatter-config#description) + +Deskripsi untuk situs. Ini akan dirender sebagai tag `` di HTML halaman. + +```ts +export default { + description: 'A VitePress site' +} +``` + +### head + +- Tipe: `HeadConfig[]` +- Default: `[]` +- Dapat ditambahkan per halaman melalui [frontmatter](./frontmatter-config#head) + +Elemen tambahan untuk dirender di tag `` di HTML halaman. Tag yang ditambahkan pengguna dirender sebelum tag penutup `head`, setelah tag VitePress. + +```ts +type HeadConfig = + | [string, Record] + | [string, Record, string] +``` + +#### Contoh: Menambahkan favicon + +```ts +export default { + head: [['link', { rel: 'icon', href: '/favicon.ico' }]] +} // letakkan favicon.ico di direktori public, jika base diatur, gunakan /base/favicon.ico + +/* Akan merender: + +*/ +``` + +#### Contoh: Menambahkan Google Fonts + +```ts +export default { + head: [ + [ + 'link', + { rel: 'preconnect', href: 'https://fonts.googleapis.com' } + ], + [ + 'link', + { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: '' } + ], + [ + 'link', + { href: 'https://fonts.googleapis.com/css2?family=Roboto&display=swap', rel: 'stylesheet' } + ] + ] +} + +/* Akan merender: + + + +*/ +``` + +#### Contoh: Mendaftarkan service worker + +```ts +export default { + head: [ + [ + 'script', + { id: 'register-sw' }, + `;(() => { + if ('serviceWorker' in navigator) { + navigator.serviceWorker.register('/sw.js') + } + })()` + ] + ] +} + +/* Akan merender: + +*/ +``` + +#### Contoh: Menggunakan Google Analytics + +```ts +export default { + head: [ + [ + 'script', + { async: '', src: 'https://www.googletagmanager.com/gtag/js?id=TAG_ID' } + ], + [ + 'script', + {}, + `window.dataLayer = window.dataLayer || []; + function gtag(){dataLayer.push(arguments);} + gtag('js', new Date()); + gtag('config', 'TAG_ID');` + ] + ] +} + +/* Akan merender: + + +*/ +``` + +### lang + +- Tipe: `string` +- Default: `en-US` + +Atribut lang untuk situs. Ini akan dirender sebagai tag `` di HTML halaman. + +```ts +export default { + lang: 'en-US' +} +``` + +### base + +- Tipe: `string` +- Default: `/` + +URL dasar tempat situs akan di-deploy. Anda perlu mengatur ini jika berencana men-deploy situs Anda di bawah sub path, misalnya, GitHub pages. Jika Anda berencana men-deploy situs Anda ke `https://foo.github.io/bar/`, maka Anda harus mengatur base ke `'/bar/'`. Ini harus selalu dimulai dan diakhiri dengan slash. Base relatif tidak didukung. + +Base secara otomatis ditambahkan di depan semua URL yang dimulai dengan / di opsi lain, jadi Anda hanya perlu menentukannya sekali. + +```ts +export default { + base: '/base/' +} +``` + +## Routing + +### cleanUrls + +- Tipe: `boolean` +- Default: `false` + +Ketika diatur ke `true`, VitePress akan menghapus `.html` di akhir URL. Lihat juga [Generating Clean URLs](../guide/routing#generating-clean-urls). + +::: warning Diperlukan Dukungan Server +Mengaktifkan ini mungkin memerlukan konfigurasi tambahan di platform hosting Anda. Agar berfungsi, server Anda harus dapat menyajikan `/foo.html` ketika mengunjungi `/foo` **tanpa redirect**. +::: + +### rewrites + +- Tipe: `Record` + +Mendefinisikan pemetaan direktori kustom <-> URL. Lihat [Routing: Route Rewrites](../guide/routing#route-rewrites) untuk detail lebih lanjut. + +```ts +export default { + rewrites: { + 'source/:page': 'destination/:page' + } +} +``` + +## Build + +### srcDir + +- Tipe: `string` +- Default: `.` + +Direktori tempat halaman markdown Anda disimpan, relatif terhadap root proyek. Lihat juga [Root and Source Directory](../guide/routing#root-and-source-directory). + +```ts +export default { + srcDir: './src' +} +``` + +### srcExclude + +- Tipe: `string[]` +- Default: `undefined` + +Pola [glob](https://github.com/mrmlnc/fast-glob#pattern-syntax) untuk mencocokkan file markdown yang harus dikecualikan sebagai konten sumber. + +```ts +export default { + srcExclude: ['**/README.md', '**/TODO.md'] +} +``` + +### outDir + +- Tipe: `string` +- Default: `./.vitepress/dist` + +Lokasi output build untuk situs, relatif terhadap [root proyek](../guide/routing#root-and-source-directory). + +```ts +export default { + outDir: '../public' +} +``` + +### assetsDir + +- Tipe: `string` +- Default: `assets` + +Menentukan direktori untuk menyarangkan aset yang dihasilkan. Path harus berada di dalam [`outDir`](#outdir) dan di-resolve relatif terhadapnya. + +```ts +export default { + assetsDir: 'static' +} +``` + +### cacheDir + +- Tipe: `string` +- Default: `./.vitepress/cache` + +Direktori untuk file cache, relatif terhadap [root proyek](../guide/routing#root-and-source-directory). Lihat juga: [cacheDir](https://vitejs.dev/config/shared-options.html#cachedir). + +```ts +export default { + cacheDir: './.vitepress/.vite' +} +``` + +### ignoreDeadLinks + +- Tipe: `boolean | 'localhostLinks' | (string | RegExp | ((link: string, source: string) => boolean))[]` +- Default: `false` + +Ketika diatur ke `true`, VitePress tidak akan menggagalkan build karena dead link. + +Ketika diatur ke `'localhostLinks'`, build akan gagal pada dead link, tetapi tidak akan memeriksa tautan `localhost`. + +```ts +export default { + ignoreDeadLinks: true +} +``` + +Ini juga dapat berupa array dari string URL persis, pola regex, atau fungsi filter kustom. + +```ts +export default { + ignoreDeadLinks: [ + // abaikan URL persis "/playground" + '/playground', + // abaikan semua tautan localhost + /^https?:\/\/localhost/, + // abaikan semua tautan yang menyertakan "/repl/" + /\/repl\//, + // fungsi kustom, abaikan semua tautan yang menyertakan "ignore" + (url) => { + return url.toLowerCase().includes('ignore') + } + ] +} +``` + +### metaChunk + +- Tipe: `boolean` +- Default: `false` + +Ketika diatur ke `true`, mengekstrak metadata halaman ke chunk JavaScript terpisah alih-alih meng-inline-nya di HTML awal. Ini membuat payload HTML setiap halaman lebih kecil dan membuat metadata halaman dapat di-cache, sehingga mengurangi bandwidth server ketika Anda memiliki banyak halaman di situs. + +### mpa + +- Tipe: `boolean` +- Default: `false` + +Ketika diatur ke `true`, aplikasi production akan dibangun dalam [Mode MPA](../guide/mpa-mode). Mode MPA mengirimkan 0kb JavaScript secara default, dengan mengorbankan penonaktifan navigasi sisi klien dan memerlukan opt-in eksplisit untuk interaktivitas. + +## Tema + +### appearance + +- Tipe: `boolean | 'dark' | 'force-dark' | 'force-auto' | import('@vueuse/core').UseDarkOptions` +- Default: `true` + +Apakah akan mengaktifkan mode gelap (dengan menambahkan kelas `.dark` ke elemen ``). + +- Jika opsi diatur ke `true`, tema default akan ditentukan oleh skema warna pilihan pengguna. +- Jika opsi diatur ke `dark`, tema akan menjadi gelap secara default, kecuali pengguna secara manual mengubahnya. +- Jika opsi diatur ke `false`, pengguna tidak akan dapat mengubah tema. +- Jika opsi diatur ke `'force-dark'`, tema akan selalu gelap dan pengguna tidak akan dapat mengubahnya. +- Jika opsi diatur ke `'force-auto'`, tema akan selalu ditentukan oleh skema warna pilihan pengguna dan pengguna tidak akan dapat mengubahnya. + +Opsi ini menyuntikkan script inline yang memulihkan pengaturan pengguna dari local storage menggunakan kunci `vitepress-theme-appearance`. Ini memastikan kelas `.dark` diterapkan sebelum halaman dirender untuk menghindari flickering. + +`appearance.initialValue` hanya dapat berupa `'dark' | undefined`. Ref atau getter tidak didukung. + +### lastUpdated + +- Tipe: `boolean` +- Default: `false` + +Apakah akan mendapatkan timestamp terakhir diperbarui untuk setiap halaman menggunakan Git. Timestamp akan disertakan dalam data halaman setiap halaman, dapat diakses melalui [`useData`](./runtime-api#usedata). + +Ketika menggunakan tema default, mengaktifkan opsi ini akan menampilkan waktu terakhir diperbarui setiap halaman. Anda dapat menyesuaikan teksnya melalui opsi [`themeConfig.lastUpdatedText`](./default-theme-config#lastupdatedtext). + +## Kustomisasi + +### markdown + +- Tipe: `MarkdownOption` + +Mengonfigurasi opsi parser Markdown. VitePress menggunakan [Markdown-it](https://github.com/markdown-it/markdown-it) sebagai parser, dan [Shiki](https://github.com/shikijs/shiki) untuk menyorot sintaks bahasa. Di dalam opsi ini, Anda dapat memberikan berbagai opsi terkait Markdown sesuai kebutuhan Anda. + +```js +export default { + markdown: {...} +} +``` + +Periksa [deklarasi tipe dan jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) untuk semua opsi yang tersedia. + +### vite + +- Tipe: `import('vite').UserConfig` + +Meneruskan [Vite Config](https://vitejs.dev/config/) mentah ke Vite dev server / bundler internal. + +```js +export default { + vite: { + // opsi config Vite + } +} +``` + +### vue + +- Tipe: `import('@vitejs/plugin-vue').Options` + +Meneruskan [opsi `@vitejs/plugin-vue`](https://github.com/vitejs/vite-plugin-vue/tree/main/packages/plugin-vue#options) mentah ke instance plugin internal. + +```js +export default { + vue: { + // opsi @vitejs/plugin-vue + } +} +``` + +## Build Hooks + +Build hooks VitePress dapat digunakan untuk menambahkan fungsionalitas dan perilaku baru ke situs Anda: + +- Sitemap +- Search Indexing +- PWA +- Teleports + +### buildEnd + +- Tipe: `(siteConfig: SiteConfig) => Awaitable` + +`buildEnd` adalah build CLI hook, ini akan berjalan setelah build (SSG) selesai tetapi sebelum proses VitePress CLI keluar. + +```ts +export default { + async buildEnd(siteConfig) { + // ... + } +} +``` + +### postRender + +- Tipe: `(context: SSGContext) => Awaitable` + +`postRender` adalah build hook, dipanggil ketika rendering SSG selesai. Hook ini dapat digunakan untuk menangani konten teleports selama SSG. + +```ts +export default { + async postRender(context) { + // ... + } +} +``` + +```ts +interface SSGContext { + content: string + teleports?: Record + [key: string]: any +} +``` + +### transformHead + +- Tipe: `(context: TransformContext) => Awaitable` + +`transformHead` adalah build hook untuk menambahkan tag tambahan ke `` setiap halaman. Hook ini dapat digunakan untuk menambahkan entri head yang tidak dapat ditambahkan secara statis ke config VitePress Anda. Anda hanya perlu mengembalikan entri tambahan, mereka akan digabungkan secara otomatis dengan yang sudah ada. + +::: warning +Jangan memutasi apa pun di dalam `context`. +::: + +```ts +export default { + async transformHead(context) { + // ... + } +} +``` + +```ts +interface TransformContext { + page: string // mis. index.md (relatif terhadap srcDir) + assets: string[] // semua aset non-js/css sebagai URL publik yang sepenuhnya di-resolve + siteConfig: SiteConfig + siteData: SiteData + pageData: PageData + title: string + description: string + head: HeadConfig[] + content: string +} +``` + +Hook ini hanya dipanggil ketika melakukan build, tidak dipanggil selama dev. + +Tag tambahan akan ditambahkan ke file HTML statis yang dihasilkan oleh build. Mereka tidak akan diperbarui selama navigasi sisi klien. + +Dalam banyak kasus, menggunakan hook [`transformPageData`](#transformpagedata) adalah solusi yang lebih bersih. Hook itu juga akan diterapkan pada navigasi sisi klien dan selama dev. Namun jika menghasilkan tag head membutuhkan komputasi yang mahal, maka `transformHead` akan menghindari overhead tersebut selama dev. + +#### Contoh: Menambahkan meta `og:image` + +```ts +export default { + async transformHead(context) { + if (context.page === '404.md') { + return + } + + // Detail implementasi `generatePageImage` akan bergantung + // pada kebutuhan Anda. Di sini kita asumsikan ia menghasilkan + // gambar yang sesuai untuk setiap halaman dan mengembalikan URL gambar. + const imageUrl = await generatePageImage(context) + + return [[ + 'meta', + { name: 'og:image', content: imageUrl } + ]] + } +} +``` + +Di sini kita mengasumsikan bahwa URL gambar bersifat dinamis dan memakan waktu untuk dihasilkan. Menggunakan `transformHead` menghindari overhead tersebut selama pengembangan. + +Untuk kasus yang lebih sederhana, mungkin dapat menggunakan pengaturan [`head`](./frontmatter-config#head) di frontmatter, atau [`transformPageData`](#transformpagedata). + +### transformHtml + +- Tipe: `(code: string, id: string, context: TransformContext) => Awaitable` + +`transformHtml` adalah build hook untuk mentransformasi konten setiap halaman sebelum disimpan ke disk. + +::: warning +Jangan memutasi apa pun di dalam `context`. Selain itu, memodifikasi konten html dapat menyebabkan masalah hidrasi di runtime. +::: + +```ts +export default { + async transformHtml(code, id, context) { + // ... + } +} +``` + +### transformPageData + +- Tipe: `(pageData: PageData, context: TransformPageContext) => Awaitable | { [key: string]: any } | void>` + +`transformPageData` adalah hook untuk mentransformasi `pageData` setiap halaman. Anda dapat langsung memutasi `pageData` atau mengembalikan nilai yang diubah yang akan digabungkan ke dalam data halaman. + +::: warning +Jangan memutasi apa pun di dalam `context` dan berhati-hatilah bahwa ini dapat memengaruhi kinerja server pengembangan, terutama jika Anda memiliki beberapa permintaan jaringan atau komputasi berat (seperti menghasilkan gambar) di hook. Anda dapat memeriksa `process.env.NODE_ENV === 'production'` untuk logika kondisional. +::: + +```ts +export default { + async transformPageData(pageData, { siteConfig }) { + pageData.contributors = await getPageContributors(pageData.relativePath) + } + + // atau kembalikan data untuk digabungkan + async transformPageData(pageData, { siteConfig }) { + return { + contributors: await getPageContributors(pageData.relativePath) + } + } +} +``` + +```ts +interface TransformPageContext { + siteConfig: SiteConfig +} +``` + +#### Contoh: Menambahkan `` + +```ts +export default { + transformPageData(pageData) { + const title = pageData.frontmatter.layout === 'home' + ? 'VitePress' + : `${pageData.title} | VitePress` + + pageData.frontmatter.head ??= [] + pageData.frontmatter.head.push([ + 'meta', + { name: 'og:title', content: title } + ]) + } +} +``` + +#### Contoh: Menambahkan URL kanonikal `` + +```ts +export default { + transformPageData(pageData) { + const canonicalUrl = `https://example.com/${pageData.relativePath}` + .replace(/index\.md$/, '') + .replace(/\.md$/, '.html') + + pageData.frontmatter.head ??= [] + pageData.frontmatter.head.push([ + 'link', + { rel: 'canonical', href: canonicalUrl } + ]) + } +} +```