Skip to content

OortCloudGroup/oort-docs

Repository files navigation

奥尔特云资源中心文档

项目描述

奥尔特云资源中心文档项目意在提供一个vue 组合 markdown 驱动的静态网站生成器,以 Markdown 为中心的项目结构,以最少的配置帮助你专注于文档输出。 项目采用vuepress 开源工程,VuePress 会为每个页面预渲染生成静态的 HTML,同时,每个页面被加载的时候,将作为 SPA 运行。

项目使用gitlab pages 以及github pages 部署

访问 gitlab pages

访问 github pages

项目结构

├── .github                              # github action 自动化部署相关文件
├── docs
   ├── .vuepress                        #  用于存放全局的配置、组件、静态资源等。
      ├── components                   # 该目录中的 Vue 组件将会被自动注册为全局组件。
      ├── images                       # 自定义组件布局vue 的资源文件 
      ├── public                       # 页静态资源目录
      ├── style                        # 用于存放样式相关的文件
         ├── index.styl               # 将会被自动应用的全局样式文件,会生成在最终的 CSS 文件结尾,具有比默认样式更高的优先级
         ├── palette.styl             # 用于重写默认颜色常量,或者设置新的 stylus 颜色常量。
      ├── config.js                    # 配置文件的入口文件,也可以是 YML  toml
      ├── navigator.js                 # 导航栏配置
      ├── sidebar.js                   # 侧边滑动框配置
   ├── guide                            # markdown 文件夹
   ├── index.md                         # 项目首页
├── .gitignore.js                        # git 忽略文件配置
├── .gitlab-ci.yml                       # git 忽略文件配置
├── package.json                       

     

项目运行(使用yarn包依赖管理)

开发(文档编写)


yarn start
yarn start:hot-reload     // 热更新

生成静态文件

默认情况下,文件将会被生成在 .vuepress/dist,当然,你也可以通过 .vuepress/config.js 中的 dest 字段来修改


yarn docs:build

yarn docs:build # 或者:npm run docs:build 默认情况下,文件将会被生成在 .vuepress/dist,当然,你也可以通过 .vuepress/config.js 中的 dest 字段来修改

项目约定

遵循 “约定优于配置” 的原则,

默认的页面路由

此处我们把 docs 目录作为 targetDir (参考 命令行接口), 下面所有的“文件的相对路径”都是相对于 docs 目录的。在项目根目录下的 package.json 中添加 scripts

{
  "scripts": {
    "dev": "vuepress dev write_docs",
    "build": "vuepress build write_docs"
  }
}

对于上述的目录结构,默认页面路由地址如下:

文件的相对路径 页面路由地址
/README.md /
/guide/README.md /guide/
/config.md /config.html

部署

gitlab

.gitlab-ci.yml 配置,现已经配置好了,只推送代码到gitlab 就会自动构建 更新gitlab pages

github

通过 github action 只推送代码到gitlab 就会自动构建 更新github pages

注意: 自己的账号需要设置secrets

oortcloudsmart 部署

修改config.js 的 base 为相应的路径 eg: base: '/oort/oortcloud-frontservice/oort-docs/', // 部署到公司环境

编写文档

使用markdwon编写

侧边栏

侧边栏的显示以及层级关系由 sidebar 来控制

Releases

No releases published

Packages

No packages published

Languages