文档中心帮助

# 关于文档中心

# 简介

金蝶Apusic 文档中心是一个在线文档中心，供咨询售前顾问、技术顾问、产品实施交付查阅和学习最新的产品文档内容。

支持中间件、云平台（含智能运维）、大数据 三大产品线的产品文档内容
- 中间件：AAS/ALB/ADMQ/AMDC/ALB/ASG
- 云平台：AUMP/统一管理平台（云原生）/ADOP
- 智能运维：AMP/AAPM/AILP/AAlarm/AIops
- 大数据：AMDM/AESB/AIDM/AMDM/ADPR/ADXP
文档中心提供标签、分页、搜索、离线PDF文档下载等功能。

产品正式发版，配套的产品文档将同步上线到到Apusic文档中心。文档中心构建生成的PDF格式文档可以在详情页下载，也可以访问知识中心-工作文档库的存档文件进行查阅。

# 技术说明

文档中心地址 docs.apusic.com(opens new window) (opens new window)
文档中心代码仓库 gitlab (opens new window) (opens new window)（桌面云内外网同地址）
采用了云之家扫码登录云之家开发文档(opens new window) (opens new window)
项目使用Vuepress搭建 Vuepress(opens new window) (opens new window)
主题使用vuepress-theme-vdoing vuepress-theme-vdoing(opens new window) (opens new window)
文档中引用的图片可以使用图床，地址 Apusic图床 (opens new window)

# 基础约定

# 文档目录

目录层级

文档中心分为产品类别、产品、版本、文档四个目录层级

源目录（一般是docs）底下的级别现在我们称之为一级目录(产品类别)，一级目录的下一级为二级目录(产品)。

产品目录

一级目录（产品类别）
1. 如01.middleware
二级目录（产品）
1. 如01.middleware\00.aas
2. 必须有序号
三级目录（版本）
1. 如01.middleware\00.aas\00.V10_0
2. 必须有序号
四级目录（文档）
1. 如01.middleware\00.aas\00.V10SP7\01.overview.md。
2. 必须有序号

# 文档标准命名

md文档统一使用英文命名，文档的具体中文名称在文档内容的front-matter中使用title属性指定。

表1.文档命名标准

MD文档	文档说明
00.release-notes.md	发版说明
01.overview.md	产品简介
02.whitepaper.md	产品白皮书
03.function-list.md	功能清单
04.quickstart.md	快速入门
05.installing.md	安装手册
06.development.md	用户手册
07.user-manual.md	开发手册
08.api.md	API文档
09.adapter.md	适配说明
10.plugin.md	插件说明
11.performance.md	性能说明
12.performace-tuning.md	性能调优手册
13.data-migration.md	数据迁移手册
14.faq.md	常见问题
15.release-history.md	版本发布历史

# 图片目录命名

文档的图片，统一存储在assets目录下，不允许使用img、image、media等命名。该目录下根据不同的文档，对应具体的子目录存储不同文档的图片，目录名称和对应的文档的名称基本保持一致，方便更新维护管理。

表2.文档引用的图片目录命名

图片目录名	文档	对应的MD文档
assets/release-notes	发版说明	00.release-notes.md
assets/overview	产品简介	01.overview.md
assets/whitepaper	产品白皮书	02.whitepaper.md
assets/functions	功能清单	03.functions.md
assets/quickstart	快速入门	04.quickstart.md
assets/installing	安装手册	05.installing.md
assets/user-manual	用户手册	06.user-manual.md
assets/development	开发手册	07.development.md
assets/api	API文档	08.api.md
assets/adapter	适配说明	09.adapter.md
assets/plugin	插件说明	10.plugin.md
assets/performance	性能说明	11.performance.md
assets/faq	常见问题	12.faq.md

# 命名

无论是文件还是文件夹，请为其名称添加上正确的正整数序号和.，从00或01开始递增，如01.文件夹、02.文件.md，文档中心将会按照序号的顺序来决定其在侧边栏及目录页当中的顺序。
同一级别目录别内即使只有一个文件或文件夹也要为其加上序号。
文件或文件夹名称中间不能出现多余的点.，如01.我是.名称.md中间出现.将会导致解析错误，必须要使用分隔符的，况建议使用_分割。

提示

序号并不一定需要连着，如01、02、03...，实际工作中可能会在两个文档中间插入一篇新的文档。因此为了方便可以采用间隔序号10、20、30...，后面如果需要在10和20中间插入一篇新文档，可以给定序号15。
所有目录级别内至少有一个文件或文件夹。

# MarkDown规范

文件必须以h2标题开始、h1标题将不会显示在右侧文档当前页内容导航栏。
图片资源续放在各产品文件夹内的assets文件夹下，并以相对路径引用，如04.更多\01.产品样例\assets\subfolder-name\title.png

//md中引用
![这里是图片名称.png](./assets/subfolder-name/title.png)

1
2

文件或文件夹名称中间不能出现多余的点.，图片不得用中文。

# 文档编写指引

# 新增产品目录

在合适的产品类别文件夹下创建新增产品的文件夹，可以通过调整序号调整顺序，各产品团队仅需维护自己的产品文件夹。

以ALB为例，产品文件夹路径为\docs\01.middleware\01.alb。

下面以ALB产品为例：

创建docs/01.中间件产品/01.alb目录
在docs/01.中间件产品/01.alb目录下创建README.md
图片资源存放在docs/01.中间件产品/01.alb/assets

# 新增产品文档

参考步骤：

在gitlab仓库相应的产品目录下，新建.md文件；
编辑好文档并提交到remote branch分支，合并PR到master,会触发webhook自动部署到在线文档服务器。
刷新页面http://https://docs.apusic.com/ 就可以查看新提交的文档内容。

# 文档元数据

Markdown可以使用 front Matter 来描述文档元数据信息，front matter 必须是 markdown 文件中的第一部分，用于该Markdown文档的相关辅助信息描述，并用于文档内容展示。

front matter支持如下三种格式：

Yaml
JSON
TOML

Apusic文档中心采用Yaml格式定义front matter。任何包含 YAML front matter 的 Markdown 文件都将由 gray-matter (opens new window) (opens new window)处理。，并且必须采用在三点划线---之间书写的有效的 YAML。

这是文档中心的一个Yaml 格式的front matter的例子：

---
title: 文档中心使用说明
date: 2021-10-13 19:35:58
permalink: /pages/help/
tags: 
  - 使用指南
categories: 
  - 帮助
---

1
2
3
4
5
6
7
8
9

# title

类型: string
默认值: h1_title || siteConfig.title

当前页面的标题。

# permalink

类型: string
默认值: siteConfig.permalink

页面永久链接，可以指定该页面一个url。

参考VuePress: Permalinks (opens new window)

# tags

类型: array
默认值: undefined

给文档设定标签。文档标签会显示于首页的热门标签中，修改front matter中的tags可以给文档打上标签。

参考VuePress: 默认主题配置 > 内置搜索 (opens new window)。

# categories

类型: array
默认值: undefined

给文档设定分类，文档分类名称将在文档生成的PDF文件标题中展现。

PDF文件的标题由categories和title 组合生成，如果categoires有多个值，则使用最后一个。

# isPDF

类型：boolean
默认值：true

该页面是否可以生成PDF，默认true，执行 yarn pdf时将md文件转换生成PDF文件，并且在文档内容详情页可以点击下载按钮下载该PDF文件。

# 更多

关于front matter更多元数据预定义变量，请参考VuePress官网 Front Matter (opens new window)。

# 文档摘要

文档摘要会显示于首页的详细版文章列表中，在编写文章时（.md文件中）在合适的位置添加一个注释。注释前面的内容将会暴露在摘要中。

![产品目录](/fenlei.png)

文档中心分为`产品类别`、`产品`、`版本`、`文档`四个目录层级

<!-- more -->

1
2
3
4
5

# 配置顶部导航栏

新产品文档完成内容后，可以添加到顶部导航栏。

你可以这样使用：

添加到导航栏在docs/.vuepress/config.js将该文件添加至侧边导航栏或顶部导航栏。
在文档中引用
直接访问访问http://localhost:8080/alb/test.html

# 如何配置

docs/.vuepress/config.js: 配置文件的入口文件

注意

修改了配置文件需要重新启动

# 配置顶部导航栏

nav:[ // 导航栏配置
      {text: '帮助', link: '/' },
      {text: '产品文档', link: '/alb/USER_GUIDE' }
    ]

1
2
3
4

# 配置侧边栏

sidebar: {
      '/alb/': [
        {
          title: '快速开始',   // 必要的
          collapsable: false, // 可选的, 默认值是 true,
          sidebarDepth: 1,    // 可选的, 默认值是 1
          children: [
            '',
            'test'
          ]
        },
        {
          title: '帮助文档',
          children: [['USER_GUIDE','用户手册'],'https','plugins'],
          collapsable: false,
          sidebarDepth: 1,
        }
      ],

      // fallback
      '/': [
        ''
      ]
    }

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 构建和调试

本部分描述如何在开发本地环境编写、构建文档，并进行相关调试。

# 本地启动

在本地启动文档服务器

yarn docs:dev

构建静态资源包

yarn docs:build

构建后的资源放置在.vuepress/dist文件夹中。

生成PDF

yarn pdf

设置定时每天23:00更新pdf

Jenkins流水线配置脚本路径docs-center/Jenkinsfile。

# 部署

文档中心配置了webhook，监听了master分支的更新，执行git pull以及yarn docs:build

可以在gitlab中手动触发执行。

# 总结

# 如果你是一名产品经理

从master分支中创建产品分支
编写文档，提交代码到自己的远程分支
提交PR到master，合并分支
触发自动部署，在站点中查看效果

# 如果你是一名开发人员

拉取代码， yarn下载依赖，yarn docs:dev启动项目
编写文档，提交代码到自己的远程分支，在本地调试
提交PR到master，合并分支
触发自动部署，在站点中查看效果

编辑页面

#使用指南

← 功能清单 PDF使用说明→