# 文档写作平台使用入门
介绍文档写作平台的运行方式,如何编写文档及各方面资源的内容组织
# 文档写作平台项目地址
# 项目运行方式
- 安装
nodejs
,在 nodejs 官网 (opens new window) 下载并安装
windows 下建议下载Windows 安装包 (.msi) 64 位
- 安装
yarn
,在 yarn 官网 (opens new window) 下载并安装 - 安装
git
,在 git 官网 (opens new window) 下载并安装好 - 下载并安装 git 图形化工具,推荐使用的有 TortoiseGit (opens new window)、SourceTree (opens new window)、Fork (opens new window)
- 克隆文档写作平台到本地环境
- 使用命令行进入到文档写作平台目录
- 运行命令
yarn install
安装依赖库 - 运行命令
yarn dev
运行本地开发平台 - 运行完成后,命令行界面中会提示访问地址,在浏览器中访问该地址即可开始进行写作,效果如下
- 此时可开始写作,并在网页中实时预览效果
- 写作完成后,将内容提交并推送到项目托管地址
success [16:22:08] Build 42920d finished in 3668 ms!
> VuePress dev server listening at http://localhost:8080/
2
只进行文档写作,不希望本地运行网站服务的情况,仅需执行 3、4、5、11
步骤
# 文档写作
Markdown 标记语言语法
- https://www.w3cschool.cn (opens new window)
- https://www.markdown.cn/ (opens new window)
- https://markdown-zh.readthedocs.io/en/latest/ (opens new window)
- http://wow.kuapp.com/markdown/ (opens new window)
推荐编辑器
文档写作平台项目基于 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
那么在文档中引用该图片的方式为

渲染结果
可以看到 /
资源引用的根位置指向了 /.vuepress/public/
WARNING
如果设置的图片是项目 Logo、二维码(App 或 小程序等),必须按照以下格式使用
<img src="/xxx.jpg" class="img">
图片将以 150 X 150
的统一规格(像素)显示
- 文档或其它
引用其它资源,区别仅为引用方式上,假设有一个文档存放于以下位置
/.vuepress/public/design/file.docx
该文档的引用方式为
[file](/design/file.docx)
根据观察可以发现,文件的引用方式与图片的引用方式上的区别仅是一个 !
,而在描述一个链接时增加感叹号则是专用于图片显示
附件类型的在点击后,会直接弹出浏览器下载窗口下载该文件,所以该方式适用于与文档内容相关的附件设置