用 vitePress 快速創建一個文檔項目

其實開發一個項目最需要的就是操作文檔，文檔的質量決定了項目的開發流程，開發規范等等。

對於前端框架來說，文檔最友好的還是vue，不僅是中國人的框架，而且文檔支持了中文。仔細查看 Vue 的官方文檔，還有Vue-Router,Vuex,Vite。發現尤大的文檔都是一個模板刻出來的，而且也非常簡潔好用。

原來是使用了VitePress這個框架生成的文檔，讓我們快速熟練使用這個框架。

於是我也自己寫了一個react-ant-admin的文檔，使用 VitePress 開發非常快，於是我完成了doc-react-ant-admin的文檔書寫。

doc-react-ant-admin 文檔源碼

安裝使用

• 1. 創建目錄

D:>mkdir vitpress_demo && cd vitpress_demo

• 2. 包管理工具初始化

D:\vitpress_demo>npm init -y

• 3. 安裝 vitepress 依賴

D:\vitpress_demo>npm i vitepress -D

• 4. 創建docs文件夾

D:\vitpress_demo>mkdir docs

• 5. 在docs文件夾下創建 index.md文件並寫入內容

# hello world

• 6. 創建 npm 腳本，快速啟動，

找到package.json修改scripts項為以下內容

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}

• 7. npm 腳本啟動項目

D:\vitpress_demo>npm run docs:dev

打開 http://localhost:3000 即可

配置介紹

在docs文件夾下創建.vitepress文件夾，並在.vitepress文件夾下創建config.js

config.js 文件內容需要導出一個模塊，這個模塊里的內容需要自己定義，才會在生效。而且每次更改需要重啟項目才會生效。

module.exports = {
  title: "react-ant-admin", // 頂部左側標題
  base: "/doc-react-ant-admin/", // 項目的根路徑
  head: [
    // 設置 描述 和 關鍵詞
    [
      "meta",
      { name: "keywords", content: "react react-admin ant 后台管理系統" },
    ],
    [
      "meta",
      {
        name: "description",
        content:
          "此框架使用與二次開發，前端框架使用react，UI框架使用ant-design，全局數據狀態管理使用redux，ajax使用庫為axios。用於快速搭建中后台頁面。",
      },
    ],
  ],
  themeConfig: {
    sidebar: {
      // 側邊欄
      "/": [
        {
          text: "介紹",
          children: [
            { text: "什么是react-ant-admin？", link: "/" },
            { text: "開始使用", link: "/guide/start" },
            { text: "文件配置", link: "/guide/configuration" },
            { text: "路徑配置", link: "/guide/path" },
          ],
        },
      ],
    },
    nav: [
      // 頂部右側導航欄
      { text: "介紹", link: "/", activeMatch: "^/$|^/guide/" },
      {
        text: "預覽地址",
        link: "https://azhengpersonalblog.top/react-ant-admin/",
      },
      {
        text: "更多地址",
        link: "/contact/",
      },
    ],
  },
};

使用注意

在docs文件夾下創建的md文件會以docs文件夾為路徑映射

• 舉例

docs
├─ .vitepress
├─ test
│   ├─ index.md     url路徑 /test/ 
│   └─ start.md     url路徑 /test/start.html       
├─ guide            
│   ├─ configuration.md     url路徑 /guide/configuration.html
│   └─ start.md             url路徑 /guide/start.html  
└─ index.md         url路徑 /