天联信息研发文档平台

# 文档写作平台使用入门

介绍文档写作平台的运行方式，如何编写文档及各方面资源的内容组织

# 文档写作平台项目地址

doc-press (opens new window)

# 目录结构

doc-press
│  package.json
│  README.md // 项目主页
│  
├─.vuepress // 文档平台引擎配置及资源文件目录
│  │  config.js        // 文档平台总体设置，如无需要，不建议对该文件进行修改
│  │  navigator.js     // 导航栏配置
│  │  sidebar.js       // 侧边栏配置
│  │  
│  │  // 资源文件，图片、文档等需要被显示或挂载的内容
│  │  // 目录结构应与文档结构一致，以免长期使用后结构混乱，难以维护
│  └─public
│     │  logo.png // 公司 logo
│     │  
│     ├─standard
│     │  
│     ├─... 
│     │  
│     └─team
│         ├─design
│         │  
│         ├─...
│         │  
│         └─guide
│  
├─adm // 行政管理
│  
├─guide // 平台使用指南及帮助相关文档
│  
├─product // 公司产品总体介绍相关内容
│  
├─project // 项目管控相关
│  
├─standard // 标准及规范相关，不建议随意修改该部分内容
│  
├─team // 团队技术文档，每个团队以独立目录进行内容维护
│  ├─android
│  │  
│  ├─backend
│  │  
│  ├─design
│  │  
│  ├─frontend
│  │  
│  ├─ios
│  │  
│  └─quality
│  
└─util // 内部工具导航

# 项目运行方式

  1. 安装 nodejs，在 nodejs 官网 (opens new window) 下载并安装，windows 下建议下载 Windows 安装包 (.msi) 64 位
  2. 运行命令 npm install -g yarn 安装 yarn
  3. 安装 git，在 git 官网 (opens new window) 下载并安装好
  4. 下载并安装 git 图形化工具，推荐使用的有 TortoiseGit (opens new window)、SourceTree (opens new window)、Fork (opens new window)
  5. 克隆文档写作平台到本地环境
  6. 使用命令行进入到文档写作平台目录
  7. 运行命令 yarn install 安装依赖库
  8. 运行命令 yarn dev 运行本地开发平台
  9. 运行完成后，命令行界面中会提示访问地址，在浏览器中访问该地址即可开始进行写作，效果如下
  10. 此时可开始写作，并在网页中实时预览效果
  11. 写作完成后，将内容提交并推送到项目托管地址
success [16:22:08] Build 42920d finished in 3668 ms!
> VuePress dev server listening at http://localhost:8080/

只进行文档写作，不希望本地运行网站服务的情况，仅需执行 3、4、5、11 步骤

# 导航结构配置

文档平台的访问形式通常以 头部导航栏 进行内容模块导航，进入相应内容模块后，再通过 侧边栏 对内容进行分类分组呈现

# 头部导航栏

/.vuepress/navigator.js 文件为头部导航栏配置文件，对应头部导航栏的应用，不应超过 三级 节点

# 单节点

类似于 标准与规范 模块的单一节点，无子节点的应用场景

{ text: '标准与规范', link: '/standard/'}

link 指定的位置与工程中的实际文件夹对应，上例中的配置要求工程的根目录存在 standard 的文件夹，否则将出现访问异常

# 子节点

类似 其他 模块的节点下有多个子节点的应用场景

{
  text: '其他',
  ariaLabel: '其他',
  items: [
    { text: '查询导览', link: '/navigator'},
    { text: '项目清单', link: '/product/'},
    { text: '项目管控', link: '/project/'}
  ]
}

items 节点指定了该节点的子节点项目

# 孙节点

类似 其他 -> 帮助 -> 文档写作平台入门 结构的孙节点应用场景

{
  text: '其他', // 根节点
  ariaLabel: '其他',
  items: [
    { text: '查询导览', link: '/navigator'},
    {
      text: '帮助', // 子节点
      ariaLabel: '帮助',
      items: [
        { text: '文档写作平台入门', link: '/guide/'} // 孙节点
      ]
    }
  ]
}

# 侧边栏

定义功能模块的侧边栏菜单显示项目，这里的配置内容基于头部导航栏的访问入口

/.vuepress/sidebar.js 文件为侧边栏菜单挂载配置文件，该文件定义了通过 头部导航栏 访问到相应内容模块后，左侧菜单侧显示的内容

# 节点名

节点名称来自于 头部导航栏 定义的内容，'/team/frontend/' 对应了 navigator.js 中定义的

{ text: '前端', link: '/team/frontend/'}

所以当在导航栏中选择 前端 项目后，侧边栏中显示的菜单内容将会是 '/team/frontend/' 定义的内容

# 内容挂载

既然上述的 节点名 描述了 头部导航栏 目标位置，则节点设置的内容（列表）则定义了侧边栏中需要显示的子栏目的清单

默认文档

对于 markdown 格式的文档结构，大家约定俗地将 README.md 作为一个文件夹的默认显示文档，其作用相当于网站程序中，业界约定俗成地将 index.html 作为一个位置默认展示的网页一样

在此配置中（sidebar.js）会将 '' 内容对应为 该目录下的 README.md 文件

// 以 '团队文档 -> 前端 -> 概况' 为例，配置结构如下
'/team/frontend/overview/': [
  '', // 指定 /team/frontend/overview/REAMDE.md 作为侧边栏顶部内容
  'showcase', // 对应 /team/frontend/overview/showcase.md
  'standard',
  'http',
  ...
]

# 文档自动解析结构

对于每个页面，会自动识别文档结构，形成目录内容显示在侧边栏中，目前自动识别 3 级文档结构

# 为一级标题，会作为根级菜单项目显示在侧边栏中
## 二级标题
### 三级标题

# 文档写作

Markdown 标记语言语法

推荐编辑器

文档写作平台项目基于 VuePress 构建，具体配置内容请查看 这里 (opens new window)

# 写作方式

文档写作平台所有编写的文档均是基于 Markdown 标记语言来编写，它的特点是使用简单的符号即可清晰地描述整个文档结构和排版，仅需要普通文本编辑器即可完成，不像 Word、Excel 等格式必须安装 Microsft Office 才可以正常使用；目前 Markdown 标记语言已经被广泛使用于国内、国际各种记事本或笔记平台、知识平台、写作平台，成为一种流行的文档编写格式，且范围不仅仅是软件行业

在网站的内容组织上，一个目录或站点的默认访问位置是 index.html，这是整个互联网环境、网页服务平台、网页服务软件等组织共同形成的约定俗成的结果

在以 Markdown 标记语言为主要格式和形式的文档平台中，大家约定俗成的默认文档为 README.md（注意大小写），其功能与 index.html 一致，可以将其理解为是一个目录或是一个文档站点的里的 首页

# HTML

实际上，在文档写作平台中，所有的 Markdown 文档最终会被编译为 HTML 格式的网页作为最终展现，所以在内容的编写上可以放心使用部分 HTML 标签的排版，建议是排版方面的标签，表单类型的标签请尽可能不要使用，以免出现不可预期的问题

# 资源内容添加

在文档写作过程中，除了文档描述自身，往往需要引用图片、跳转链接和文件下载等需求来丰富文档内容

# 资源内容说明

资源可分为以下两类

  • 图片
  • 文档（Word、Excel、PowerPoint或其它类型文档）

其中，图片可在文档中直接显示，而其它类型文件可作为下载附件的方式挂载在文档中

所有资源存放位置：

/.vuepress/public/

特别注意

注意：所有资源要求必须有序存放，例如根据业务类型、团队类型等形式分目录存放

# 资源使用方式

  • 图片内容

假设有一张图片存放于以下位置

/.vuepress/public/logo.png

那么在文档中引用该图片的方式为

![logo](/logo.png)

渲染结果

logo

可以看到 / 资源引用的根位置指向了 /.vuepress/public/

特别注意

如果设置的图片是项目 Logo、二维码（App 或 小程序等），必须按照以下格式使用

<img src="/xxx.jpg" class="img">

图片将以 150 X 150 的统一规格（像素）显示

  • 文档或其它

引用其它资源，区别仅为引用方式上，假设有一个文档存放于以下位置

/.vuepress/public/design/file.docx

该文档的引用方式为

[file](/design/file.docx)

根据观察可以发现，文件的引用方式与图片的引用方式上的区别仅是一个 !，而在描述一个链接时增加感叹号则是专用于图片显示

附件类型的在点击后，会直接弹出浏览器下载窗口下载该文件，所以该方式适用于与文档内容相关的附件设置

最后更新时间: 11/24/2021, 9:19:29 AM