企业官网建设流程全解析

写技术博文时，插图最容易出两类问题：一是写到一半就先填 ``，后面改章节顺序，图还钉在旧位置；二是出图工具换了文件名，正文里一串路径要手工搜改，漏一处就成死链。把「画面要求」和「最终文件名」拆开，用占位写进正文，再统一出图、按顺序替换，这两类坑能一起压住。

直接写路径为什么会错位

写作顺序和成图顺序不同步

正文是按论证推出来的，图是按渲染队列出来的。你在第二节写了 ``，第三节又插了一段，第二节变成第四节，文件名还叫fig-02，读者会以为「第二张图对应第二节」，实际已经对不上。更糟的是预览器和发布器对相对路径、空行规则不一致：有的要求图片行上下各空一行，有的会把紧贴代码块的图吞掉。

后期改一张图要动整篇

路径写死之后，换图等于改契约：

占位的价值不在「多一种注释语法」，而在把意图（这张图要表达什么、插在哪一段旁边）和产物名（figure-01.png）解耦。

占位规划怎么写进 Markdown

约定可解析的注释块

用 HTML 注释承载结构化字段，预览时不渲染，脚本又能用正则整段抠出来。字段至少要有类型、简短 alt、出图用的画面描述：

![占位到合并三步](https://i-blog.csdnimg.cn/direct/d633ca10b6bd40809a13b272cf175868.png#pic_center)

类型建议收敛成固定词表，例如：主题图片、流程图、时序图、框架图、技术介绍图、辅助理解图、重点说明图。解析时把未知类型落到「辅助理解图」，并按类型给默认宽高（主题图常用 1280×720，流程图可略宽）。写作阶段不要写 ``，也别虚构文件名；文件名留给合并步骤按序号生成。

边写边插，张数跟着结构走

规划原则可以写死几条，避免凑图：

1. 默认 2 张；结构清晰时 2～3 张；只有某一小节确实需要画面再加，最多 5 张。
2. 占位紧贴它服务的段落：讲流程就放在流程说明附近，讲对照就放在表格前后。
3. prompt写画面约束，不写文件路径；alt 用短中文，合并后直接进 ``。

写作完成后，脚本按出现顺序解析占位，生成任务列表；出图阶段只读占位、不改正文；合并阶段再把注释块换成真正的图片行，并保证该行前后各空一行，减少平台解析差异。

解析与替换的最小实现

下面这段示意「按出现顺序收集占位 → 按同样顺序替换」，核心是顺序对齐，不是复杂 AI：

importrefromdataclassesimportdataclass FIGURE_BLOCK_RE=re.compile(r"<!--\\s*figure\\b([\\s\\S]*?)-->",re.I)KEY_RE=re.compile(r"^(type|alt|prompt)\\s*:\\s*(.*)$",re.I)@dataclassclassFigureSpec:raw:strkind:stralt:strprompt:strdefparse_fields(body:str)->dict[str,str]:fields,current,buf={},"",[]forlineinbody.splitlines():m=KEY_RE.match(line.strip())ifm:ifcurrent:fields[current]="\\n".join(buf).strip()current,buf=m.group(1).lower(),[m.group(2)]elifcurrent:buf.append(line)ifcurrent:fields[current]="\\n".join(buf).strip()returnfieldsdefparse_placeholders(text:str)->list[FigureSpec]:out=[]forminFIGURE_BLOCK_RE.finditer(textor""):f=parse_fields(m.group(1))out.append(FigureSpec(raw=m.group(0),kind=(f.get("type")or"辅助理解图").strip(),alt=(f.get("alt")or"配图").strip(),prompt=(f.get("prompt")or"").strip(),))returnoutdefreplace_one(body:str,raw:str,alt:str,filename:str)->str:md=f""returnbody.replace(raw,f"\\n\\n{md}\\n\\n",1)

出图时把kind + prompt + 文章标题拼成完整画面要求，产物命名为figure-01.png、figure-02.png…；合并时zip(占位列表, 文件列表)，一对一替换。数量对不上就失败返回，比默默少贴一张图更安全。

改图与排错时盯住这几条

只改编排意图，不动已合并路径（在合并前）

合并前改图：改占位里的prompt/type，删掉旧 PNG 再跑出图步骤即可，正文位置不变。合并后若必须换图，优先覆盖同名文件，避免改 Markdown；只有增删张数时才回头改占位并重跑解析。

空占位与假外链要提前拦

• 正文一个占位都没有：可以按标题补一张「主题图片」，但应打警告——说明作者没做画面规划。
• 禁止模型在写作阶段写example.com、picsum之类假图链；校验阶段直接删掉，只保留合法占位。
• 同一占位字符串必须唯一，替换用「首次出现」；重复 raw 会导致第二张图替换失败。

和目录、标题注释的边界

文首目录由平台脚本插入，正文里不要再写目录标记。发布标题单独放在 ``，不要再做同名一级标题，避免目录里出现两个一样的入口。配图占位是第三种「机器可读注释」：给人看的是段落，给流水线看的是type/alt/prompt。

把插图从「写到哪填到哪的文件名」改成「写到哪就钉在哪的意图描述」，错位和难替换会一起变少。你下次开新篇时，先定 2～3 个占位落点，再写论证；成图只是后一步的渲染。