图片维护

尽管图片对于用户理解非常有价值，但它们很难维护。我们采用了一些策略来简化这一工作。

我们的文档支持几种不同类型的图片，包括：

• 图表
• 屏幕截图

在这些类型中，我们更倾向于使用 Mermaid 图表，因为它们可被搜索且易于更改。更新 Mermaid 图表的“成本”远低于重新截屏或与设计师合作更新图表。

改善图片维护的最佳方法是避免使用它们。

另一种简化维护的方法是删除文档中不再被引用的图片。如果您需要针对 UI 更改或泄露信息对图片进行审计，此模式将特别有用，因为这样您就不会把时间浪费在检查未使用的图片上。

我们通过结合使用 GitHub Actions 来实现这一点。

我们有一个特定的 GitHub Action 来标记未使用的图片 ↗。

该 GitHub Action 的工作流程如下：

1. 查找我们内容中的所有 .png 或 .svg 文件。
2. 检查这些文件是否在我们任何 MDX 文件中被引用。
3. 如果存在未被引用的文件，则创建一个 GitHub issue ↗。

在标记未使用的图片的同时，我们还在构建过程 ↗中加入了验证图片路径的逻辑。

export default defineConfig({
	site: "https://developers.cloudflare.com",
	markdown: {
		smartypants: false,
		remarkPlugins: [remarkValidateImages],
		rehypePlugins: [
			rehypeMermaid,
			rehypeExternalLinks,
			rehypeHeadingSlugs,
			rehypeAutolinkHeadings,
			// @ts-expect-error plugins types are outdated but functional
			rehypeTitleFigure,
			rehypeShiftHeadings,
		],
	},

这确保了构建时的 nimbus/image-ref 静态检查（lint）规则会验证所有图片路径。如果路径不存在，我们将抛出错误并阻止网站构建。

结合标记未使用的图片来看，这种路径验证确保了技术作家可以在拉取请求中安全地删除未使用的工作文件。只要网站成功构建，就说明您仅删除了没有任何地方引用的图片文件。