我問導師，Vue3有沒有對應工具來生成漂亮的文檔？ 用 Vitepress
本文已經過原作者 Michael Thiessen 授權翻譯。
最近有人在問：小智， Vue3 有沒有對應制作文檔的工具。于是，我去查了一些資料，發現，Vue3和新的Vite構建工具為我們提供了另一種快速開發靜態站點的方法，那就是 Vitepress。
今天，我們來一起看看，如何使用 Vitepress 快速為Vue應用創建文檔。
下面是我們最后要完成的內容：
在開始之前，我們先來看看 Vitepress 是個啥東西。
Vitepress 是什么?
Vitepress是在Vite之上構建的Vue驅動的靜態站點生成器。
Vitepress 被稱為“ Vuepress的小弟弟”，它比同類產品具有一些優勢。
- 建立在Vite而非Webpack上，因此啟動時間，熱重裝等更快
- 使用Vue3來減少JS的有效負載
- 輕量級
Vitepress 能夠實現這些目標的一個原因是，它比Vuepress 更具體，而 Vuepress在過去幾年里變得更加復雜。
雖然不打算完全取代Vuepress作為 Vue 的靜態網站生成器，但 Vitepress 提供了一種輕量級的替代方案。對于大多數項目，例如文檔和簡單站點，Vitepress的特殊性和簡約性將使開發變得輕而易舉。
創建 Vitepress 項目
首先，創建目錄。
- mkdir vite-hello-world
- cd vite-hello-world
然后，初始化 package 并安裝 Vitepress。
- npm init
- npm i --save-dev vitepress
接著，在package.json中添加一些命令。
- // package.json
- "scripts": {
- "docs:dev": "vitepress dev docs",
- "docs:build": "vitepress build docs",
- "docs:serve": "vitepress serve docs"
- },
把上面安排后，再創建一個docs文件夾，制作我們的第一個markdown文件。
- mkdir docs
- echo '# Hello World' > docs/index.md
最后，給它跑起來。
- npm run docs:dev~~~~
我們已經創建了我們的網站，在瀏覽器中打開 http://localhost:3000，則會在網頁中看到我們的markdown文件!
看到這樣，有點小雞凍了，我們再來看看，如果定制自己想要的東西。
Vitepress 導航
Vitepress 添加多個頁面就像創建更多markdown文件一樣容易。我們在 docs/ 再創建一些文件，如下所示：
Vitepress 創建 SPA 導航時，它將使用每個markdown文件的路徑來創建路由。此外，任何文件夾中名為index.md的文件也只能由/引用。
例如，我們的文件結構轉換為以下路由：
- // docs/index.md
- ## Routing!
- [docs/index.md](/) -> /
- [docs/contact.md](/contact) -> /contact
- [about/index.md](/about/) -> /about/
- [about/our-story.md](/about/our-story) -> /about/our-story
在我們的md文件中，有三種跳轉到路由的方法 我們可以使用基本URL，添加.md或.html-所有這些都將正確鏈接到對應的組件。
- ### All these options work!
- [docs/contact](/contact) |
- [docs/contact.md](/contact.md) |
- [docs/contact.html](/contact.html)
添加導航欄和側邊欄
Vitepress為我們提供了一個很棒的默認主題。它雖然很小，但功能強大且易于定制。
首先，我們通過邊欄和導航欄向我們的網站添加一些導航。
為此，我們需要創建一個配置文件–我們可以在/docs/.vitepress/文件夾中進行此操作，該文件夾將存放我們的 Vitepress 特定文件，取名為./vitepress/config.js，只需要導出一個JS對象。
- // .vitepress/config.js
- module.exports = {
- title: 'Vitepress Tutorial', // appended to all page titles
- }
在這個對象中，我們再添加一個themeConfig的屬性
- // .vitepress/config.js
- module.exports = {
- title: "Vitepress Tutorial", // appended to all page titles
- themeConfig: {
- nav: [],
- sidebar: [],
- },
- };
要將元素添加到導航欄，我們只需要將對象添加到nav數組中，格式為{text：'ANCHOR-TEXT'，link：'PATH'}:
- // .vitepress/config.js
- module.exports = {
- title: "Vitepress Tutorial", // appended to all page titles
- themeConfig: {
- nav: [
- { text: "Home", link: "/" },
- { text: "About", link: "/about/" },
- { text: "Contact", link: "/contact" },
- ],
- sidebar: [
- { text: 'Our Story', link: '/about/our-story' }
- ],
- },
- };
添加側邊欄也是一樣的方式。
- // .vitepress/config.js
- module.exports = {
- title: "Vitepress Tutorial", // appended to all page titles
- themeConfig: {
- nav: [
- { text: "Home", link: "/" },
- { text: "About", link: "/about/" },
- { text: "Contact", link: "/contact" },
- ],
- sidebar: [
- { text: 'Our Story', link: '/about/our-story' }
- ],
- },
- };
回到我們的瀏覽器，我們現在可以看到 Vitepress 僅從幾行配置就生成了一個非常漂亮的導航欄和側欄。
Vitepress側邊欄可以做的一件很酷的事情是根據我們所在的頁面來更改側邊欄。
比如，我們想讓首頁顯示其標題，其他頁面都顯示我們剛剛制作的側邊欄。
我們要做的第一件事是創建將our-story側邊欄存儲為變量。
- // .vitepress/config.js
- const primarySidebar = [
- { text: 'Our Story', link: '/about/our-story' }
- ]
回到我們的themeConfig對象，我們想將側邊欄更改為一個對象，其中屬性名稱是路徑，值是側邊欄數組。
- sidebar: {
- '/about/': primarySidebar, // everything in the /about/ subdirectory
- '/contact': primarySidebar, // contact page
- }
現在，查看瀏覽器，會看到我們的主頁側邊欄與所有其他邊欄不同。
在Vitepress中內置元素
Vitepress 附帶了對幾個元素的支持，我們可以在config.js中或在Markdown中直接聲明這些元素。
這里只會在這里介紹一些最常用的內容，完整的內容點擊這里。
代碼塊
在編寫好的文檔時，代碼示例至關重要。Vitepress 提供了一種快速添加代碼塊并指定正在使用的編程語言的方法。
Github樣式表
Vitepress中的表沒接觸過 md 的小伙伴，可能會覺得有點奇怪，如下所示：
- // .vitepress/config.js
- | Headings | Are | Centered |
- | ------------- |:-------------:| -----: |
- | left align | centered | right align |
- | zebra striped | rows | easy |
Markdown Frontmatter配置
盡管我們可以使用./vuepress/config.js配置網站，但有時我們還是需要對各個頁面進行更細的控制。
幸運的是，我們可以使用markdown文件頂部的YAML塊來控制每個頁面。Vitepress通過用三個虛線(---)包圍它來聲明該塊。
- // docs/contact
- ---
- title: Contact
- ---
- # Contact
我們可以在這里配置很多不同的東西。查看所有Frontmatter選項的文檔。
部署 Vitepress 應用
我們使用npm run docs:dev創建本地環境，但是構建用于生產的應用又該怎么做呢?
可以使用以下命令來構建：
- npm run dev:build
默認情況下，構建后的文件會被放到/docs/.vuepress/dist下。
作者：Michael Thiessen 譯者：前端小智來源：news原文：https://learn.co/2021/01/write-beautul-documentation-quickly-with-vitepress/
