Markdown 写作示例

这是一篇给团队看的样板页，目的是快速看看 VitePress 默认主题里常见的 Markdown 格式长什么样。
写文档时尽量先把句子说清楚，再决定要不要加格式。
这页里我尽量把常用样式都放进来了 🎉

写作原则

文档先写结论，再写步骤，最后写例外情况。

规则要短，尽量一眼能扫完。
步骤要顺，别把前后顺序打乱。
参数名、按钮名、字段名尽量统一。

先给用户一个结果。
再给执行路径。
最后补注意事项。

建议：把容易变动的字段单独拎出来，避免整段文字都要重写。
API Key、Base URL、模型名 这类内容，适合用等宽格式突出。

跳到表格示例
 查看 VS Code Cline 配置教程
 VitePress Markdown 官方文档

图片示例

表格示例

项目	规范	备注
文件名	`kebab-case.md`	方便路由和查找
标题	先结论后解释	更适合客户快速扫读
代码	必须标明语言	便于高亮
版本	写清发布日期	防止旧内容混用

提示框示例

INFO

这里适合放背景说明，比如“某个参数只在特定场景下使用”。

TIP

这里适合放推荐做法，比如“默认先走最简单的路径”。

WARNING

这里适合放容易出错的地方，比如“不要把生产密钥写进公开页面”。

DANGER

这里适合放高风险内容，比如“不要直接把未校对的配置发给客户”。

查看一个折叠清单

标题别太长
段落别太散
每节最好只回答一个问题

GitHub 风格告警

NOTE

这类写法适合补充一个轻量说明。

TIP

这类写法适合放一个小建议。

WARNING

这类写法适合放风险提醒。

代码块示例

export interface DocRule {
  title: string
  owner: string
  status: 'draft' | 'review' | 'published'
}

export const defaultRule: DocRule = {
  title: 'Markdown 写作示例',
  owner: 'docs',
  status: 'draft'
}

export const publish = (title: string) => {
  const stage = 'review'
  if (title.length > 0) {
    return `Publish: ${title}`
  }
  return 'Missing title'
}

export const format = (input: string) => {
  const trimmed = input.trim()
  return trimmed.replace(/\s+/g, ' ')
}

diff

- 旧版写法：把说明写成一整段。
+ 新版写法：先拆成小节，再写成可执行步骤。

代码组示例

config.tsconfig.js

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'MaoMaoToken 文档'
})

export default {
  title: 'MaoMaoToken 文档'
}

文件引入示例

下面这段是通过  引入的 Markdown 片段，适合拆分长文。

这段内容来自单独的 Markdown 片段，方便多个页面复用。

适合放通用说明
适合拆成长文档
适合让多人协作时少重复写

下面这段是从独立代码文件里直接引进来的。

export interface MarkdownSample {
  name: string
  language: string
  visible: boolean
}

export const sample: MarkdownSample = {
  name: 'Markdown Demo',
  language: 'ts',
  visible: true
}

收尾

这类页面通常够用了：标题、引用、列表、表格、提示框、告警、代码块、代码组、图片和文件引入都能看出来。
如果后面你想看更进阶的，比如数学公式、Vue 组件、专门的布局，我再继续加一页。

Markdown 写作示例 ​

写作原则 ​

图片示例 ​

表格示例 ​

提示框示例 ​

GitHub 风格告警 ​

代码块示例 ​

代码组示例 ​

文件引入示例 ​

收尾 ​