Markdown 写作指南

写作空间是云赫文化统一的写作后台，产品教程和技术博客都在这里编写、保存和发布。本指南按照编辑器现有的功能逐项说明，读完即可独立完成一篇文档。

认识写作空间

右上角的 专注模式 会隐藏左侧的作品库和写作卡片列表，让编辑区占满宽度；再次点击 退出专注 即可恢复。顶部导航还可以进入 安全设置；根据账号权限，还会显示 反馈审核、用户管理 和 服务器监控。

账号与权限

写作空间按账号角色开放功能。看不到某个按钮或页面，表示当前账号没有对应的权限。

新账号由超级管理员在 用户管理 中创建，并获得一次性临时密码；首次登录时必须设置自己的登录密码。修改已发布的内容前，每个账号都需要在 安全设置 中设置自己的二级密码。

文档设置

点击标题下方的 文档设置 展开以下字段：

文档路径只能使用小写英文字母、数字、短横线、下划线和斜杠，并以字母或数字开头。发布后尽量不要再修改，以免读者收藏的链接失效。

超级管理员可以点击 ＋ 添加产品 新建产品，需要填写 产品名称、唯一标识 和 简介。唯一标识以小写字母开头，只能包含小写字母、数字和短横线，例如 my-new-app。产品下有已发布的文章后，才会出现在文档专区中。

用卡片组织写作

一个想法写一张卡片，最后按顺序拼成完整的正文。每篇文档最多 100 张卡片。

• ＋ 卡片：在列表末尾新建一张正文卡片。
• 调整顺序：直接拖动卡片，或点击卡片右下角的 ↑ / ↓。
• 卡片名称：只用于在工作区里辨认卡片，不会出现在发布的文档中。
• 拆分：把光标放在正文中间，点击 拆分，光标之后的内容会成为一张新卡片。
• 合并下一张：把下一张卡片的正文接到当前卡片末尾。两张卡片必须同为正文卡片或同为素材卡片。
• 删除：删除当前卡片。每篇文档至少保留一张卡片。

发布时，所有正文卡片按顺序拼接，卡片之间自动空一行。

素材卡片

点击 ＋ 记录素材 / 灵感 新建素材卡片，或在任意卡片上勾选 素材卡片。素材卡片适合存放参考资料、待核实的步骤和零散想法：

• 和文档一起保存在数据库中，仅管理员可见；
• 不会进入发布的正文、站内搜索和 导出全文；
• 随时可以取消勾选，把它变回正文卡片。

写作、双栏与全文预览

编辑区上方有三种视图：

• 写作：只显示当前卡片的 Markdown 源文本。
• 双栏：左侧写作，右侧实时预览当前卡片。
• 全文预览：显示所有正文卡片拼接后的完整文档，不含素材卡片。

预览与阅读页使用同一套排版规则，预览里看到的效果就是读者看到的效果。预览栏右上角显示当前内容的字符数；编辑区底部显示全文字符数和素材卡片数量。

格式工具栏

先选中文字再点击工具，会把选中的文字包进对应格式；没有选中时，会插入一段示例文字供你替换。

建议每篇文档只用一个一级标题，用二级、三级标题组织内容。二级和三级标题会出现在阅读页右侧的 本页内容 中。

高亮颜色

高亮支持 黄色、绿色、蓝色、粉色 和 紫色。不写颜色时，==文字== 默认为黄色。

列表与引用

在 段落 中选择列表或引用后，选中的每一行都会加上对应前缀：

- 无序列表
1. 有序列表
- [ ] 未完成的任务
- [x] 已完成的任务
> 引用的一段话

任务列表在阅读页显示为复选框，读者不能勾选，适合写检查清单。

插入内容

点击工具栏的 ＋ 插入 可以加入以下内容。

脚注

选择 脚注，填写说明后确认。编辑器会在光标处插入编号，例如 [^1]，并把说明写到当前卡片末尾。编号会自动避开其他卡片中已经使用的编号。阅读页会把所有脚注集中显示在文末，并提供返回原文的链接。¹

表格

选择 表格，设置 2–8 列和 1–20 行数据，编辑器会生成带表头的表格：

| 列 1 | 列 2 | 列 3 |
| --- | --- | --- |
| 内容 | 内容 | 内容 |

把表头和内容替换成实际文字即可。单元格内不要使用竖线 |，否则会被识别为新的一列。

标注

选择 标注，挑选类型、填写标题和内容。标题留空时显示类型名称。

此外，也可以手动输入 > [!DANGER]，显示为红色的 警告。

分隔线

选择 分隔线，插入 ---，用于分开前后两部分内容。

代码块

选择 代码块，填写代码语言（如 javascript、python，可留空）和代码。代码按原样显示，不做语法着色；如果代码本身包含反引号，编辑器会自动加长代码块的围栏。

const steps = ['准备工作', '操作步骤', '预期结果'];
console.log(steps.join(' → '));

数学公式

选择 数学块，用 LaTeX 写公式，编辑器会插入独占一行的数学块：

$$
t = \frac{N}{f}
$$

段落中的行内公式用一对美元符号包住，例如 $E = mc^2$。公式在预览和阅读页都会排版显示，例如：

链接

选择 链接，填写显示文字和地址。可以使用：

• https:// 或 http:// 开头的网址，读者点击后会在新标签页打开；
• mailto: 邮件地址；
• 以 / 开头的站内路径，例如 /docs/feedback.html；
• 指向其他文档的 Markdown 文件名，例如 [阅读指南](reading-guide.md)，发布后会自动跳转到对应的文档页。

图片

插入图片有两种方式：

• 上传图片：选择 PNG、JPG、WebP 或 GIF 文件，单张不超过 5 MB，暂不支持 SVG。上传后会在光标处插入图片，保存文档后生效。
• ＋ 插入 → 图片链接：填写图片说明和 HTTPS 地址或站内路径。

![设置面板中的渲染选项](https://example.com/screenshot.png)

上传图片时，默认用文件名作为图片说明，建议改成能描述图片内容的文字。

导入、读取与导出

编辑区底部提供以下操作：

公开的阅读页不提供下载。需要把文档保存到本地时，请在写作空间中打开它，再点击 导出全文 ↓。

导入和读取的 Markdown 文件须为 UTF-8 编码，不超过 250 KB；卡片备份文件不超过 550 KB。导入时如果文档路径为空，会根据文件名自动生成。

• 读取外部网站的文件，需要对方服务器允许跨域读取；读取失败时，可以先下载到本地再导入。
• Markdown 文件中引用的本地相对路径图片不会随文件上传，请重新上传图片，或改成可以公开访问的网址。
• 导入和读取都不会自动保存或发布。

自动备份与恢复

输入内容后，编辑器会自动把当前文档备份到本浏览器，底部状态显示“已自动备份到本浏览器”。这份备份不在数据库中：

• 重新打开这篇文档时，如果发现未保存的备份，会提示 恢复编辑 或 丢弃备份；
• 切换到其他文档前，若有未保存的修改，编辑器会先提醒你；
• 清除浏览器数据或更换电脑后，本地备份会丢失。需要长期保留时，请使用 保存草稿 或 备份卡片。

保存、发布与撤回

• 保存草稿（Ctrl/⌘ + S）：把全部卡片和素材写入数据库。草稿仅管理员可见。
• 发布文档：正文卡片对读者公开，文档专区、阅读页目录和站内搜索立即更新。发布前至少要有一张填写了内容的正文卡片。
• 保存更新：文档发布后，保存草稿 会变为 保存更新，保存后公开版本随之更新。
• 查看发布页 ↗：在新标签页打开公开的阅读页。
• 撤回：把已发布的文档改回草稿，读者将无法访问。

正文最大 250 KB，全部卡片合计最大 500 KB。内容较长时，请拆分成多篇文档。

如果提示“文档已被其他窗口更新”，说明这篇文档在别处被修改过。请先点击 备份卡片 或 导出全文 保存当前内容，再重新打开文档，对照后再保存。

已发布内容的二次验证

曾经发布过的文档，包括已撤回或从回收站恢复的文档，在 保存更新、撤回 或 移入回收站 时都需要二次验证：

1. 在弹出的窗口中输入 二级密码；
2. 抄写窗口中显示的 6 位随机验证码；
3. 点击 确认操作。

验证码五分钟内有效，只能确认本次操作；点击取消不会丢失编辑内容。

回收站

点击 移入回收站 可以删除文档，这是软删除，文档不会立即消失。在作品库的筛选中选择 回收站 可以找到它，点击 恢复为草稿 即可恢复。恢复后的文档如果再次修改或发布，仍然需要二次验证。

技术博客与多语言

• 技术博客会以卡片形式列在文档专区首页，显示标题、摘要、作者、日期和语言。
• 文档专区的界面支持简体中文、English、日本語、한국어、Русский 和 Español。
• 编辑器不会自动翻译正文，每种语言的文章都是一篇独立的文档。读者切换到没有对应译文的语言时，会看到原文和一条提示。

发布前检查清单

• 正文以一级标题开头，小节使用二级、三级标题
• 文档设置中的内容类型、产品、分组、路径和顺序都已确认
• 每张图片都有清楚的说明，并能正常显示
• 链接可以打开，指向其他文档的链接跳转正确
• 在 全文预览 中通读一遍，确认素材卡片没有误设为正文
• 已保存草稿，再点击 发布文档