# VitePress + Shiki - 你也可以成為文件大師！
- [前言](#前言)
- [Shiki](#Shiki)
- [功能特色](#功能特色)
- [應用場景](#應用場景)
- [開始使用](#開始使用)
- [VitePress vs. Nuxt Content vs. Docus](#VitePress-vs-Nuxt-Content-vs-Docus)
- [趨勢圖](#Run-chart)
- [比較表](#Comparison-table)
- [VitePress](#VitePress)
- [功能特色](#功能特色1)
- [應用場景](#應用場景1)
- [開始使用](#開始使用1)
- [Twoslash](#Twoslash)
- [功能特色](#功能特色2)
- [應用場景](#應用場景2)
- [開始使用](#開始使用2)
- [結語](#結語)

---
## 前言

平常在逛技術文件時，常會遇到 code 區塊有 syntax highlighting，比起 google 隨便搜尋到的農場文中的還要準確 / 精緻許多；且如果是 `typescript` 的區塊，甚至還能[預覽型別](https://www.typescriptlang.org/docs/handbook/utility-types.html)！


一起來揭秘到底是什麼黑魔法吧～
咻咻咻！探囊取物，現在我們得到了 `shiki`, `twoslash` 這兩個關鍵字。
以下便來一一介紹。

## Shiki

> Shiki (式, a Japanese word for "Style") ，
> 是一套基於 TextMate 語法定義的高效、輕量的程式碼 syntax highlight library。

### 功能特色
- 快速：runtime 前運行，且無需再引入任何 JavaScript，同時獲得完美的 syntax highlight。
- 跨平台：支援跨平台使用，能夠在不同的環境中實現一致的高亮效果。
- 高客製性：使用者可以輕鬆定製主題風格，以滿足不同的使用需求。

### 應用場景
適用於各種程式碼編輯器、IDE、網頁應用等，提供優秀的 syntax highlight 體驗。

### 開始使用
整合方式分 `extension` 與 `built-in`
- **Extension**
- [Shiki](https://github.com/shikijs/shiki)
- (Nuxt) [nuxt-shiki](https://github.com/pi0/nuxt-shiki)
- **Built-in**
- [VitePress (built-in)](https://github.com/vuejs/vitepress)
- (Nuxt) [Nuxt Content (built-in)](https://github.com/nuxt/content)

安裝方式請自行參考官方文件

### Demo
- 使用 `nuxt-shiki`，將 Rhinix 中的 component `DevCode`，從 `highlight.js` 改用 `shiki` - [Preview](https://preview-shiki-highlight.dev.rhinoshield.tw/demo/slider) / [MR](https://gitlab.com/evolutivelabs/website/rhinix/-/merge_requests/682)

<br>

---

## `VitePress` vs. `Nuxt Content` vs. `Docus`

比較一下上面提到的 `VitePress`, `Nuxt Content`，還有一套也很新的 `Docus`

### [Run chart](https://npmcharts.com/compare/@nuxt-themes/docus,vitepress,@nuxt/content)

### Comparison table
| Name | Stars | Contributors | Last Released | Notes |
| -------- | -------- | -------- | -------- | -------- |
| [VitePress](https://github.com/vuejs/vitepress) | 10.4K | 300 | 2024-03-06 | Evan You + Anthony Fu |
| [Nuxt Content](https://github.com/nuxt/content) | 2.9K | 200 | 2024-03-07 | 各代 Nuxt lead |
| [Docus](https://github.com/nuxt-themes/docus) | 1.4K | 50 | 2023-10-06 | 各代 Nuxt lead |

<br>

---

## VitePress

> VitePress 是一個基於 Vite 和 Vue 的靜態網站產生器，為快速構建簡潔的文件網站而設計。
> Shiki 已是其 built-in

### 功能特色
- 簡潔易用：VitePress 提供簡潔的文件撰寫方式，使用 Markdown 語法快速編寫文件內容。
- 快速建置：利用 Vite 的快速編譯能力，實現快速的站點建置和瀏覽體驗。
- 主題定製：支援豐富的主題定製功能，讓用戶根據自身需求定製站點風格。

### 應用場景
適用於各種技術 blog 以及 API 文件的快速建置和部署。

### Demo
Demo time... 之後再附上 repo

<br>

---

## Twoslash

> Twoslash 是一個能夠在 Markdown 文件中執行 TypeScript 程式碼的工具，提供即時編譯和顯示結果的功能。

#### 功能特色
- 即時編譯：Twoslash 能夠即時編譯 Markdown 文件中的 TypeScript 代碼，並將執行結果直接顯示在文件中。
- 客製化配置：支援豐富的配置選項，用戶可以根據需要調整編譯和顯示的行為。
- 整合性強：Twoslash 能夠與各種文件生成工具（如 VitePress）良好整合，為文件提供更豐富的交互性。

#### 應用場景
適用於各種需要在文檔中展示程式碼執行結果的情境，可幫助學習 TypeScript 以及豐富 API 文件。

#### Demo
Demo time... 之後再附上 repo(跟上面同一個)

<br>

---

## 結語

以上工具不管是開發或是查閱文件已經是相對容易，妥善的文件將達到輔助開發的效果。
在記錄自己足跡的同時，也能增強開發者對於產品的表達性，以及降低大腦的記憶負擔。