# persagy-vue-doc

persagy-vue-doc 项目提供在 vuepress 文档上引入 git 源代码功能。目前只支持基于 gogs 的 git 仓库。 

## 安装

修改项目文件 “package.json”。在 “dependencies” 项目下增加 "@persagy-vue-doc"依赖。

``` javascript
  "dependencies": {

    ......

    "@persagy-vue-doc": "^1.1.21",

    ......

  },
```

* 注：版本不定时更新，版本号请根据发布的最新版本修改。

在 Windows 控制台 或 IDE 开发环境的控制台窗口，切换到文档项目所在文件夹。执行以下安装命令。

``` shell
npm install
```

## 引入组件
修改项目文件 “docs/.vuepress/enhanceApp.js“，如果不存在则创建该文件。

``` javascript
import Vue from "vue"
import PDoc from "persagy-vue-doc"
Vue.use(PDoc);
```



### 属性

| 属性 | 说明 | 默认值 | 必须 |
|:---:|---|:---:|:---:|
| repos | git 仓库名称 | - | 是 |
| src | 源码路径 | - | 是 |
| branch | 分枝 | master | - |
| lang | 语言 | javascript | - |

* 组件访问的 git 地下："/gogs/" + repos + "/raw/" + branch + src
* 如果读取的分枝不是主分析时，需要指定 branch 属性；
* lang 支持的语言有： javascript, css, html, xml, java, kotlin, c, c++, C#, python, kotlin 等等。

### 配置代理
git 仓库与文档可能不在一个服务器上，这将导至跨域访问问题。因此，需要配置代理来解决跨域问题。

#### 开发环境配置
修改 vuepress 项目的项目配置文件 “docs/.vuepress/config.js”。在 module.exports 配置中增加 git 代理设置。

``` javascript
module.exports = {

    ......

    devServer: {
        proxy: {
            '/gogs/': {
                target: 'http://39.106.8.246:3003',
                ws: true,
                changeOrigin: true,
                pathRewrite: {
                    '^/gogs/': '/'
                },
                bypass: function(req, res, proxyOptions) {
                    req.headers["Authorization"] = "Basic Z29nczoxMjM0NTY="
                }
            }
        }
    }
}
```

说明：
* /gogs/ 代理：如果前缀为 ”/gogs/“ ，则执行代理；
* target: 设置 "/gogs/" 前缀被转向的目标地址；
* changeOrigin: 是否支持跨域；
* pathRewrite: 代理到目标地址后，url 的变更。该例为将 ”/gogs/“ 前缀变更为 ”/“。
* bypass: 在发出代理请求时执行的动作。示例中是在发出 git 源理请求时，在请求头中加入认证信息。
* 认证信息后的串为 git 请求的用户名与用户密码。格式为： ”<用户名>:<用户密码>“ 。例如，”gogs:123456“。经过 Base64 加密码后即为上述字符串。