sybotan-vue-doc

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

安装

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

  "dependencies": {

    ......

    "sybotan-vue-doc": "^1.1.21",

    ......

  },

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

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

npm install

引入组件

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

import Vue from "vue"
import SDoc from "sybotan-vue-doc"
Vue.use(SDoc);

SCodeGit 组件

SCodeGit 组件用于在文档中引入 git 代码。例如，以下代码引用 git 仓库 ”libs/sybotan-ts“ 的代码 ”/base/src/core/SObject.ts“。

<SCodeGit repos="libs/sybotan-ts" src="/base/src/core/SObject.ts" lang="javascript"></SCodeGit>

属性

| 属性 | 说明 | 默认值 | 必须 | |:---:|---|:---:|:---:| | 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://git.sybotan.com',
                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 加密码后即为上述字符串。

nginx 服务器配置

nginx 的配置文件在 ”/etc/nginx/conf.d/“ 文件夹下。以下示例为文档放在 http://docs.sybotan.com ，gogs 仓库部署在 http://git.sybotan.com 的示例配置。

server {
    listen         80;
    server_name    docs.sybotan.com;

    location / {
        root   /web/docs;
        index  index.html index.htm;
    }
    location /gogs {
        proxy_pass http://git.sybotan.com;
        proxy_set_header Authorization "Basic Z29nczoxMjM0NTY=";
        rewrite  ^/gogs/(.*)$ /$1 break;
    }
}

• ”location /gogs“ ：该段配置 nginx 的代理。关于 nginx 代理更详细信息请自行在网络上查找相关说明；
• proxy_pass： 设置 "/gogs/" 前缀被转向的目标地址；
• proxy_set_header：在发出代理请求时执行时在请求头中加入认证信息。
• rewrite: 代理到目标地址后，url 的变更。该例为将 ”/gogs/“ 前缀变更为 ”/“。