外观
如何写一篇文档
文档全部是 Markdown 文件(后缀 .md),用记事本就能写,不需要懂网页。
三步新增一篇
- 建文件:在
docs/kb/下新建一个文件,比如docs/kb/meeting.md。文件名用英文小写,不要用空格和中文。 - 写内容:第一行写
# 标题,然后正常写正文。 - 加目录:打开
docs/.vitepress/config.mts,在sidebar的「知识库」里加一行:
ts
{ text: '会议纪要规范', link: '/kb/meeting' }改完重新构建发布,左侧目录里就会出现这一篇。
文件放在哪
| 目录 | 放什么 |
|---|---|
docs/index.md | 首页,一般不用动 |
docs/kb/ | 知识库正文,你的文档都放这里 |
docs/guide/ | 站点使用说明、写作规范 |
docs/public/ | 图片、附件,引用时从 / 开始写 |
Markdown 速查
md
# 一级标题(每篇只有开头一个)
## 二级标题
### 三级标题
普通段落直接写。**加粗**、*斜体*、`行内代码`。
- 无序列表
- 第二项
1. 可以嵌套有序列表
1. 有序步骤
2. 第二步
> 引用:用来放提示或注意事项
[链接文字](https://example.com)
[站内跳转](./process.md)
| 列名 | 说明 |
| --- | --- |
| 内容 | 单元格 |
```bash
npm run build
```提示框
用三个冒号可以做出带颜色的提示块:
md
::: tip 小提示
这是提示内容
:::
::: warning 注意
这是警告内容
:::
::: danger 危险
这是危险提示
:::插入图片
- 把图片放到
docs/public/images/下,比如docs/public/images/flow.png。 - 在文档里这样引用:
md
图片路径以 / 开头,不要写 ./ 或本地绝对路径,否则发布后会 404。
上传 PDF / Word / Excel 附件
不需要为每个文件建一篇文档。 直接把文件放进 docs/public/files/ 目录,重新构建后会自动出现在「文件柜」页面里。
步骤
- 打开
docs/public/files/文件夹。 - 把 PDF(或 Word、Excel、PPT、zip)拖进去。
- 想分类就建子文件夹,比如
文件柜/营销制度/、文件柜/安全规程/,页面会按文件夹分组。 - 双击
build.bat,重新发布。
文件名可以直接用中文,保持和原文一致就好,方便查找。只有一点要注意:文件名里别带 #、%、? 这几个符号,它们在网址里有特殊含义。
想让某个文件出现在正文里
在任意文档中链接它:
md
[下载原文](</files/营销制度/某某通知.pdf>)链接地址要用 /files/ 开头,并且放在尖括号 <> 里(因为中文和空格会让普通写法解析失败)。
几个约定
- 文件名:英文小写 + 连字符,如
expense-rule.md。改文件名等于改网址,改完要同步改目录里的链接。 - 标题:一篇文档只用一个
#,各级标题按顺序用,不要跳级。 - 一句话一段:手机上更好读。
- 先结论后细节:把最常用的信息放最前面。