Home

Awesome

Erda 用户文档

文档开发

提前安装好 node >= 12

npm i # 如果已安装过依赖,可跳过
npm run dev

本地服务启动后,按提示访问(默认是http://localhost:8080/)即可看到预览效果,改动后自动刷新。 如果某个改动导致页面白屏,可能是js报错了,需要重启一下服务再尝试。

文档结构

docs
  - .vuepress 项目配置
    - nav     导航菜单配置
    - sidebar 侧边栏菜单配置
    - ...     其他前端文件,基本不用修改
  - 2.0       2.0版本文档
  - next      下个版本文档
  - en
    - 2.0 英文版2.0文档

vuepress会把除.vuepress目录以外的目录下,所有的markdown、vue文件,按照同样的目录结构转为html文件。 每个目录下的 README.md 会作为 index.html。 推荐每个目录都有一个 README.md 文件,避免用户访问某一个路径时出现404的问题。

导航菜单配置

.vuepress/nav/zh.js中修改

module.exports = [
  {
    text: '使用手册',
    link: '/manual/' // 有最后的/时,表示是个目录,需要有/manual/README.md
  },
  {
    text: 'CHANGELOG',
    link: '/changeLog' // 没有最后的/时,表示是个文件,需要有/changeLog.md文件
  },
  {
    text: 'FAQ',
    link: '/faq'
  },
  {
    text: '了解更多',
    ariaLabel: '了解更多',
    items: [ // 有多级菜单时
      {
        text: '产品架构',
        link: '/architecture'
      },
      {
        text: '其他',
        items: [
          {
            text: 'Changelog',
            link: 'https://github.com/vuejs/vuepress/blob/master/CHANGELOG.md'
          }
        ]
      }
    ]
  },
]

侧边栏菜单配置

.vuepress/sidebar/zh.js中修改

  '/doc/guide/': [] // 按最先匹配到的,所以精确匹配的要放在前面
  '/doc/': [ // 匹配路径,前后都有/,当在这个路径下时,使用下面的配置作为菜单
    {
      title: '快速上手',
      collapsable: true, // 是否可折叠
      children: [ // 二级菜单
        'guide/', // 添加key作为路径前缀,这个指向/doc/guide/README.md
        'guide/getting-started', // 指向/doc/guide/getting-started.md
        '../api/cli', // 其他目录下的使用相对路径,这个指向/api/cli.md
      ]
    },
    {
      title: 'groupB',
      collapsable: true,
      children: [
      ]
    }
  ],

默认情况下,侧边栏会自动地显示由当前页面的标题(headers)组成的链接,并按照页面本身的结构进行嵌套,你可以通过以下代码来修改它的行为。 默认的深度是 1,它将提取到 h2 的标题,设置成 0 将会禁用标题(headers)链接,同时,最大的深度为 2,它将同时提取 h2 和 h3 标题。

---
sidebarDepth: 0
---

如果所有内容都在一个文件内,且侧边栏没有分组,或分组不需要展开收起,可以直接在该文件头部添加如下内容, 可以自动根据h1\h2\h3层级生成侧边栏菜单

---
sidebar: auto
---

设置主页模板

在任意文件顶部加入如下代码,会在该页加入首页的模板,就是一个logo+描述+按钮+footer

---
home: true
heroImage: //terminus-paas.oss-cn-hangzhou.aliyuncs.com/paas-doc/2020/06/09/0b9da3f2-8aa6-4a5f-b649-96f09d874c25.png
actionText: 快速上手
actionLink: /manual/guide/getting-started
footer: Copyright © 2012-present terminus
---

注意事项

不要在文档中直接写 {{ }}, 除非用 ``` 代码块包裹,否则应使用以下任意一种方式:

<code v-text="'{{ ... }}'"/>
<code v-pre>{{ ... }}</code>
{{'{\{ ... }\}'}}

其他

支持类型:

<Badge type="warning" text="beta" />
::: tip 这是提示标题
这是一个提示
:::
<ClientOnly>
  <video-player title="测试视频" src="https://static.erda.cloud/site/video/erda.mp4"></video-player>
</ClientOnly>

更多配置参考vuepress官方文档

编辑流程

  1. 新建 feature 分支,完成初稿,提交前执行npm run lint-md检查文档格式,没问题后执行提交
  2. 比较 feature 分支和 develop 分支发 Merge Request, 完成 Review 后合并分支
  3. 定期把 develop 分支 merge 到 master 分支, 进行升级

编写规范

  1. 截图使用 Mac 14 寸小屏非全屏(Shift + Command + 4 + 空格 + 单击) ,注意隐藏书签(Shift + Command + B)、关闭无关 Tab 页、项目图片请选择比较正式的terminus图片,项目或应用描述请填写比较正式的描述信息。
  2. 截图使用内部 Uploader 服务上传至 OSS。
  3. 中英文混排,英文前后必须有空格。
  4. 不要使用类似<project>这样用尖括号包裹的占位符,如果需要使用请用代码块包裹起来

发布版本

注意,目前只会保留最近三个版本的文档,next 目录为当前迭代中的文档,每个迭代完成后,从 next 目录 release 出新版本文档

  1. 复制一份 next 目录并改名为新版本
  2. .vuepress/sidebar/vers 目录下增加新版的左侧菜单配置
  3. 移动旧版本目录到 archive 目录下,避免影响打包速度,因为 vuepress 会扫描 docs 目录下所有文件