persagy-vue/persagy-vue-doc/README.md

persagy-vue-doc

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

安装

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

  "dependencies": {

    ......

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

    ......

  },

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

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

npm install

引入组件

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

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 代理设置。

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 加密码后即为上述字符串。