AI绘画教程Markdown编写：技术文档风格的教学内容创作与排版
我有一个GitHub仓库专门用来存AI绘画的Prompt笔记——两年下来攒了300多个.md文件。一开始只是随便写写，后来发现来Star的人越来越多，有人甚至提Issue问我"你的Markdown模板能不能分享一下"。我才意识到，写好一份AI绘画教程的Markdown文档本身就是一门手艺——它不是把Word文档另存为.md就完事了，而是要考虑代码高亮、目录结构、图片引用路径、在不同平台（GitHub、Notion、博客）上的渲染一致性。这篇把我这两年踩过的排版坑和总结出来的最佳实践整理出来，适合想系统整理AI绘画知识的朋友。
标准Markdown语法在AI绘画教程中的特殊用法
普通技术文档的Markdown规范大家都熟——但AI绘画教程有自己的特殊需求：Prompt块需要代码高亮但不应该用纯代码块、生成图需要对比展示（原图vs生成图）、参数表需要用表格但Markdown表格对中文支持很差。这些特殊场景需要一些"非标准但好用"的写法。
Prompt块的展示——用围栏代码块加自定义语言标识。不写```写```prompt或者```text——前者在GitHub上虽然不会高亮但会给读者"这是Prompt"的视觉暗示。更好的写法："用blockquote（>）嵌套代码块来区分Prompt和说明文字——外层>是说明，内层```是Prompt本身"。这样在Notion和Obsidian里渲染效果都很好。参数表——Markdown原生表格对中文列宽处理很差，建议用"| 参数 | 值 | 说明 |"三列结构，每列内容控制在一行以内。如果某列内容长——单独起一段用列表补充。
图片嵌入与对比展示的最佳实践
AI绘画教程里图片是核心资产——但很多人对图片的处理极其粗糙：一张大图直接甩进去、没有alt文本、没有缩放控制、没有对比图布局。好的图片排版至少要考虑四点：原图vs生成图的并排对比、图片的alt文本对SEO和无障碍访问的影响、不同平台的图片渲染差异、以及图片的懒加载策略。
并排对比图——在GitHub上用HTML table实现（Markdown不支持并排图片）。<table><tr><td><img src="before.png"></td><td><img src="after.png"></td></tr></table>。在Notion里直接拖两张图到分栏布局。alt文本不是随便写的——"a photorealistic portrait generated by Midjourney v6 using the prompt above"比"生成图"有价值一百倍。关于图片SEO，Google图片SEO指南里的建议是：alt文本应该描述图片内容，让搜索引擎"理解"这张图在说什么。
层级结构与目录自动生成
一个超过3000字的AI绘画教程如果没有目录——读者的体验跟没有地图走迷宫差不多。三层以上的标题结构建议在文档开头加锚点目录。
GitHub风格的目录——直接在文档顶部写："- [第一章：Prompt基础](#1-prompt基础)\n - [1.1 提示词结构](#11-提示词结构)"。每个标题的锚点ID是标题的小写化+连字符+去除特殊符号。这个目录在GitHub、GitLab、Gitee上都能自动跳转。如果发布到Hexo/Hugo等静态博客——目录需要用模板语法生成，不要在Markdown里手动写。Obsidian用户可以直接用"## 目录"加上核心插件自动生成——但注意Obsidian的Wiki链接语法([[page]])和标准Markdown链接不兼容——发布到其他平台前要替换为标准链接。结构化文档的组织逻辑可以参考Markdown Guide的层级规范。
不同发布平台的适配策略
同一份AI绘画教程要在五个地方发：GitHub、个人博客、知乎、小红书（截图）、B站专栏。每个平台的Markdown渲染规则都不一样——你不能写一份.md然后到处复制。
GitHub——最宽松的环境，支持大多数GFM扩展语法，支持HTML嵌入，支持Mermaid图表。写最完整的版本放在GitHub上作为"源文档"。个人博客（Hexo/Hugo/VuePress）——需要处理frontmatter（YAML头）、静态资源路径（相对路径改绝对路径或CDN地址）、以及代码高亮主题。知乎——Markdown支持有限：不支持HTML、不支持表格合并、不支持脚注、代码块只能用```text。提前准备好"知乎精简版"——去掉表格、去掉HTML、把复杂格式降级为简单列表。小红书——Markdown完全没用，直接把文档截图或用Canva做成信息图卡片。关于跨平台内容分发的更多策略，见AI内容发布指南和AI教程写作技巧。
Prompt模板库的Markdown管理法
我现在的Prompt库管理方式是：一个主目录文件（index.md）+ 按主题分类的子文件 + 一个YAML格式的元数据文件。这套结构在Obsidian里展示效果最好，但导出到其他平台也不费劲。
主目录格式：按"人物/场景/风格/特殊效果"四个大类分——每个大类下面用二级标题分子类，每个子类下面用三级标题写单个Prompt。每个Prompt条目包含：标题、适用模型（MJ/SD/DALL-E）、难度、Prompt原文、参数、参考图（如有）、注意事项。如果你用Obsidian——给每个Prompt条目加一个#tag标签方便搜索；如果你用GitHub——利用GitHub的搜索功能直接搜文件名和内容。更高效的做法是配合AI Prompt组织系统建立跨平台的Prompt管理流程。
常见问题
Markdown里嵌入的图片链接应该用相对路径还是绝对路径？
看你发布到哪里。GitHub仓库内——相对路径最好（./images/prompt-result.png），因为克隆到本地后图片依然能显示。个人博客——绝对路径（CDN地址），因为你的.md文件可能在不同目录下被引用，相对路径会失效。跨平台发布——建议用绝对CDN链接（如https://cdn.example.com/images/xxx.png），这样在任何平台渲染都不会丢图。如果图床挂了——你所有文档的图片全部裂开——所以建议在本地保留一份完整的images文件夹作为备份。
写AI绘画教程时Prompt太长——Markdown代码块里怎么换行不影响读者复制？
Prompt在代码块里如果超过80个字符一行——GitHub会出水平滚动条，对手机端读者极其不友好。解法：用软换行——在代码块里按语义断行（每个逗号或分号后面断），但保证复制粘贴到AI工具里后仍然是完整的一句话。更友好的做法：在代码块下面加一个"一键复制"的HTML按钮（仅GitHub支持）——用<details>折叠标签把完整Prompt包起来，默认折叠、点击展开——适合特别长的Prompt。
怎么让Markdown教程的SEO更好——搜索引擎能读到图片和Prompt吗？
搜索引擎读不到图片里的文字——包括你截图里的Prompt。所以：图片的alt文本必须写清楚图片内容；每个Prompt除了在代码块里展示还要在正文里用文字描述一遍——这段描述就是给搜索引擎读的"可索引内容"。如果你用SSG（Hugo/Hexo）生成页面——在frontmatter里写description和keywords。搜索引擎对代码块内容的索引权重低于正文——所以重要概念要在正文段落里出现，不能只放在代码块里。站内文章之间的互链（尤其是从高权重页面链向新页面）也是SEO的关键——关于站内SEO布局见AI绘画站内SEO优化指南。