# 文档写作平台使用入门

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

# 文档写作平台项目地址

doc-press (opens new window)

# 项目运行方式

  1. 安装 nodejs,在 nodejs 官网 (opens new window) 下载并安装
    windows 下建议下载 Windows 安装包 (.msi) 64 位
  2. 安装 yarn,在 yarn 官网 (opens new window) 下载并安装
  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/
1
2

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

# 文档写作

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/

WARNING

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

# 资源使用方式

  • 图片内容

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

/.vuepress/public/logo.png

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

![logo](/logo.png)

渲染结果

logo

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

WARNING

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

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

图片将以 150 X 150 的统一规格(像素)显示

  • 文档或其它

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

/.vuepress/public/design/file.docx

该文档的引用方式为

[file](/design/file.docx)

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

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

最后更新时间: 8/1/2019, 9:21:48 AM