跳到正文

Markdown 与链接

编写页面元数据、行内链接、列表、表格和提示,并为插图提供替代文本。

页面元数据

在 frontmatter 中填写 title 和 description。标题概括读者的任务或要查找的对象。描述用一句话交代适用场景、用途或结果,便于在搜索中识别页面。

---
title: 配置缓存
description: 为静态文件设置缓存有效期,并确认响应头已经生效。
---

## 设置缓存有效期

把链接加在关键词上

把链接放在句子中对应的术语、页面名或操作名称上,让链接文字单独读起来也能说明目标。引用外部资料时,把资料名放进同一句话。句号留在链接外,随正文一起标点。

例如,可以按中文排版规范调整正文中的标点和间距。

请按[中文排版规范](/docs/typography/overview)调整正文中的标点和间距。

站内链接优先指向当前语言的页面。较长的页面可以链接到具体小节。改动标题或移动文件后,从预览页复制实际生成的锚点,并检查引用该小节的链接。链接到上游参考时,优先使用与说明相符的版本。

在链接与锚点一页可以对照链接文字、跨页地址、固定版本和锚点的完整写法。

列表、表格和插图

列表项使用平行的句式。完整的句子带句号,同组的短语可统一省略句末标点。表头写出字段和单位,单元格保留适合比较的信息。

图片的替代文本写出读者要从图中获知的事实。截图可以指明要辨认的控件和状态。页面操作步骤应包含完成任务所需的文字,图片用于补充位置或结果。

在列表与表格中查找编号、嵌套和表头规则,或按替代文本示例给图片补充语义。

提示与强调

把补充信息放在相关步骤附近。影响数据、权限或兼容性的说明放在操作之前,并写明影响范围和读者需要采取的动作。使用提示块时,先确认目标文档站支持相应语法。

加粗需要扫读的界面标签或关键条件。用行内代码标记命令、路径、参数和代码标识符。

复查 Markdown 源码

标题、列表、围栏代码块和表格之间用空行区分。代码块写明语言并闭合围栏。连续几个嵌套元素组合时,先确认外层结构的缩进,再查看完整渲染。写组件前,可以先在本文档站的 MDC 写法中确认支持的语法。