前端文档

基于vitepress 搭建在线文档模板,支持 markdown 标题搜索,vue3 组件与 js 代码运行

可快速搭建 vue 3.x 项目技术文档。

• gitee 部署在线文档站点
• gitee 在线文档模板
• github pages 在线文档
• markdown 代码运行与搜索组件
• vitepress 官方

如果感觉对您有用，欢迎 star

快速开始

• 克隆项目

git clone git@github.com:appbest/docs.git

• 安装

# yarn 安装
yarn

# 调试
yarn docs:dev

# 打包
yarn docs:build

vite 解决引用组件热更问题

清除缓存目录，

/node_modules/.vite_opt_cache

重要提示

• 需修改源码二级目录路径问题，参考文档底部
• 调试时可删除
• 编译缓存目录 /node_modules/.vite
• 更新搜索数据源keywords.json,删除将生成最新数据源

更新

• 更新说明

0.3.3

2022/8/19

• qve:0.4.1

0.3.2

2022/4/1

• qve:0.3.9

0.2.9

2022/1/15

• qve:0.3.5
• quick-plugin-md:0.2.3
• 支持 Less 解析
• 支持脑图插件

文档组件

• packages 文件夹

CodeRun 代码在线调试

<CodeRun dll="json" styled="height:20rem" ubb editable>

// js 在线测试执行代码
return 'test';

</CodeRun>

项目依赖

• quick.lib
• quick.plugin
• vitePress

vitepress 发布文档

图标目录

发布到服务器时需要将源图标文件夹 /docs/fonts 内容复制到打包的 /dist/ 目录

vitepress 动态组件报错

如需动态编译执行 vue 组件代码,需修改源码

• vitepress 版本 0.21.4 需修改以下路径代码 node_modeules>vitepress>dist>node>serve-3fdbda2c.js

// 第12309行注释，替换为编译
//const vueRuntimePath = "vue/dist/vue.runtime.esm-bundler.js";
const vueRuntimePath = 'vue/dist/vue.esm-bundler.js';

• vitepress 版本 0.13.0 alias配置失效，。 需修改以下路径代码 node_modeules>vitepress>dist>node>serve-3fdbda2c.js

// 第12333行注释，替换为编译
    {
      find: /^vue$/,
    // replacement: require.resolve("vue/dist/vue.runtime.esm-bundler.js")
       replacement: require.resolve("vue/dist/vue.esm-bundler.js")
    }

域名二级目录路径问题

• 目录名与文件名，请使用小写

• vitepress 0.8.1 及以下需要，当前项目无需更新。

  需要发布为二级目录时，调试正常正式发布时会导致路径错误， 需要修改以下文件。

  node_modeules\vitepress\dist\client\app\utils.js

  第 20 行（把整个 base 路径删除了导致 Bug 修改为 1 正常取值）

  //pagePath = pagePath.slice(base.length).replace(/\//g, '_') + '.md';
  
  // 网站路径替换为文档目录
  pagePath = 'docs/' + pagePath.slice(base.length);
  pagePath = pagePath.replace(/\//g, '_') + '.md';
  // console.log(base,pagePath);

git 入门

# 初始化
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin git@github.com:appbest/docs.git
git push -u origin main

github pages 部署

#!/usr/bin/env sh

# 忽略错误
set -e

# 构建
# npm run docs:build

# 进入待发布的目录
cd docs/.vitepress/dist

# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

# 如果部署到 https://<USERNAME>.github.io
# git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git master

# 如果是部署到 pages https://<USERNAME>.github.io/<REPO>
git push -f git@github.com:appbest/docs.git master:gh-pages

# 同步部署到 qve.gitee.io/docs/
git push -f git@gitee.com:qve/docs.git master:gh-pages