写作本文的动机
写本文的原因是我在为 vitepress-plugin-og-image 这个插件撰写的文档质量低，只介绍了我使用该插件时遇到的一些痛点，而缺乏对于插件更基本的使用介绍。
一篇好的使用文档需要具备的特征
可操作性
这里所说的可操作性，是指用户通过查看该文档，即能够完成插件或者应用的安装、基本配置和使用。
可阅读性
可阅读性一方面是指用户阅读本文档时的流畅阅读体验。另一方面则是指整个应用文档的各个章节之间尽量与约定好的文档规范保持一致，这样不仅便于用户理解，还有助于其他团队成员扩充你之前编写的文档当中内容不完整的地方。
编写文档的思路
插件使用文档的撰写，首先要记得把插件导入使用环境的流程讲清楚。其次是说明插件功能的实现要配置哪些文件和参数。
vitepress-plugin-og-image 插件文档的例子
以 vitepress-plugin-og-image 插件的文档编写为例，这是一个为网站首页以及每一篇博文分别生成他们的社交媒体卡片(OpenGraph)的插件。 文档首先介绍了该插件是 vitepress 静态网站生成器的插件。具体来说， 负责生成社交媒体卡片的函数叫 buildEndGenerateOpenGraphImages， 它是被一个叫buildEnd的钩子函数调用的。 在我们运行 run docs:build 命令之后，buildEnd也会随之被调用。所以要配置好插件，首先就要进入到 vitepress 的站点配置文件 .vitepress/config.ts， 在其中的 defindConfig 代码块当中添加实现 buildEnd 函数的代码。以下是示例代码：
async buildEnd(siteConfig) {
const newBuilder = buildEndGenerateOpenGraphImages({
baseUrl: 'https://yourwebesite.page',
category: {
byLevel: 2,
fallbackWithFrontmatter: true,
},
})
await newBuilder(siteConfig)
},这样就成功的在我们的 vitepress 项目中挂载了vitepress-plugin-og-image 插件。
要使用 buildEndGenerateOpenGraphImages，我们需要配置和考虑两个参数和因素：
1. baseUrl
首先，因为 Meta，Discord，Telegram 的设计，他们在服务端获取社交卡片图片（og image）的时候，会需要读取静态的，完整的图片链接，因此，我们需要指定 baseUrl 来渲染图片的链接到 ${baseUrl}/og-image.png 类似的路径上，假如 baseUrl 配置为 https://example.com/subdir，那么最终图片的链接将会被渲染和填充为 https://example.com/subdir/og-image.png。
2. 用于渲染社交卡片图片（og image）的模板 SVG 源文件
默认情况下，@nolebase/vitepress-plugin-og-image 会尝试搜索 /public 目录 下的 og-template.svg 文件，以渲染社交卡片图片。 社交媒体服务的服务器将通过 ${baseUrl}/你的博文目录结构/og-你的博文名.png这个 url 链接来获取插件为每个博文渲染好的社交媒体卡片。
总结
以上这个案例首先介绍了插件实现的功能，然后讲了如何将其倒入进一个 vitepress 项目和正确运行它的所要进行的配置。 比较遗憾的部分是它没有讲到 buildEndGenerateOpenGraphImages函数中 category 这个参数的作用，这些都是有待扩充和完成的地方。
贡献者
朵琳