# docs

**Repository Path**: qve/docs

## Basic Information

- **Project Name**: docs
- **Description**: 极简快速的文档模板，支持全站搜索markdown 与实时运行vue 3.x组件，js代码在线调试， 基于vite与vitepress 构建。支持less 解析，支持脑图显示
- **Primary Language**: JavaScript
- **License**: MIT
- **Default Branch**: main
- **Homepage**: https://qve.gitee.io/docs/
- **GVP Project**: No

## Statistics

- **Stars**: 22
- **Forks**: 5
- **Created**: 2020-10-07
- **Last Updated**: 2023-12-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: docs, 文档, Vue, vite, vitepress

## README

# 前端文档

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

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

- [gitee 部署在线文档站点](https://qve.gitee.io/docs/)
- [gitee 在线文档模板](https://gitee.com/qve/vitepress-template/)
- [github pages 在线文档](https://appbest.github.io/docs/)
- [markdown 代码运行与搜索组件](https://www.npmjs.com/package/quick-plugin-md)
- [vitepress 官方](https://vitepress.vuejs.org/)

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

## 快速开始

- 克隆项目

```bash

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

```

- 安装

```bash
# yarn 安装
yarn

# 调试
yarn docs:dev

# 打包
yarn docs:build
```

## vite 解决引用组件热更问题

清除缓存目录，

`/node_modules/.vite_opt_cache`

## 重要提示

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

## 更新

- [更新说明](./CHANGELOG.md)

## 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
// js 在线测试执行代码
return 'test';
```

`</CodeRun>`

## 项目依赖

- [quick.lib](https://www.npmjs.com/package/quick.lib)
- [quick.plugin](https://www.npmjs.com/package/quick-plugin-md)
- [vitePress](https://github.com/vuejs/vitepress)

## vitepress 发布文档

### 图标目录

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

### vitepress 动态组件报错

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

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

```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`

```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 正常取值）

  ```js
  //pagePath = pagePath.slice(base.length).replace(/\//g, '_') + '.md';

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

## git 入门

```sh

# 初始化
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 部署

```sh
#!/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

```