添加博客文章
目标
将用户内容添加到现有静态博客,而无需强制使用新的博客系统。
此技能必须首先理解当前网站如何表示文章,然后以该样式添加新内容。它不是一个通用的 Markdown 转 HTML 转换器。
契约
输入:
- 现有的静态网站文件夹及其当前的文章/索引/模板系统。
- 一个或多个源文章:Markdown、Obsidian 笔记、Word 文档、旧 HTML、粘贴的文本、图片、附件或内容文件夹。
- 可选的元数据,如标题、日期、标签、摘要、Slug、封面图片和导入范围。
输出:
- 与网站现有文章样式匹配的新文章/详情页面。
- 更新的入口点,如博客索引、归档、标签/分类、首页最新文章、搜索数据、RSS 或站点地图(如果这些系统已存在)。
- 使用页面相对路径复制/重新链接的本地图片和附件。
- 更新后的
EDITING.md文章说明(如适用)。
边界:
- 不要重新设计网站或在现有系统明确的情况下创建新的文章系统。
- 不要编造源内容不支持的元数据、日期、作者或声明。
- 不要静默添加远程数学/CDN 依赖。
- 不要发布;使用
publish-static-site。
成功标准:
- 新文章以现有样式呈现,并可从相应的索引访问。
- 图片、数学公式、链接、代码、表格和富内容正常工作,或明确报告未解决的问题。
- 路径是相对于文章和索引页面的页面相对路径。
- 受影响的页面通过浏览器验证,并且
review-static-site可以成功或仅报告已接受的限制。
如果成功标准失败:
- 在此技能中修复转换、元数据、路径、资源或索引连接。
- 使用
edit-site-part对导入引起的微小视觉问题进行修复。 - 修复后再次使用
review-static-site。
使用时机
当用户想要:
- 添加一篇新文章、笔记、随笔或博客帖子时使用此技能。
- 将几篇 Markdown 文件导入静态网站。
- 将文章从旧博客移动到新生成的网站。
- 将粘贴的文章文本转换为网站文章页面。
- 更新博客索引、归档、标签、首页最新文章或相关入口点。
- 在添加内容时保持当前网站的视觉语言。
不要使用此技能来选择主题、从头构建新网站、重新创建网站样式、个性化个人资料/关于内容、进行微小的视觉调整、发布网站或将项目转换为框架。
输入
使用任何可用的内容:
- 静态网站文件夹,通常是
site/、dist/、out/或public/。 - 一个或多个 Markdown 文件、Word 文档、粘贴的文章、旧 HTML 文件、图片文件夹或内容文件夹。
EDITING.md、页面地图或来自先前技能的交接说明。- 现有的文章模板页面或代表性文章。
- 用户提供的标题、日期、标签、分类、摘要、Slug、封面图片和发布偏好。
- 是导入所有文章、选定子集还是先导入代表性批次。
如果源内容很大,请先检查结构,避免盲目导入所有内容。
1. 了解现有的文章系统
在写入新文章之前,检查网站当前的工作方式。
检查:
- 文章文件,如
posts/*.html、notes/*.html、articles/*.html或嵌套路由文件夹。 - 索引页面,如
blog.html、archive/index.html、notes/index.html、tags/index.html或category/index.html。 - 数据文件,如
data/posts.json、data/notes.json、data/site.json或profile.json。 assets/script.js或类似文件中的 JavaScript 数据数组。- 首页上用于最新文章、精选文章、笔记、阅读列表或写作亮点的部分。
- 可用作模板的现有文章/详情页面。
- 现有的路径策略:模板是使用页面相对链接(如
../assets/style.css)还是服务器根链接(如/assets/style.css)。 - RSS、Atom、站点地图、搜索索引或标签/分类页面(如果已存在)。
EDITING.md中关于添加文章的说明。- 现有的图片和附件约定,如
assets/images/posts/、同位置的文章文件夹、封面字段、图形类、灯箱标记、标题或响应式图片包装器。 - 现有的富内容约定,如数学渲染、代码高亮、表格、脚注、标注、标题锚点、目录、链接卡片、嵌入、图表以及引用/参考文献部分。
遵循现有结构。当网站已有文章系统时,不要发明新的文章系统。
2. 提取文章元数据
对于每篇源文章,提取或推导:
- 标题。
- 日期。
- Slug。
- 标签或分类。
- 摘要或摘录。
- 封面图片或主图(如果存在且可用)。
- 源路径。
- 阅读时间,仅当当前网站已使用它或易于一致计算时。
使用前置元数据(如果存在)。否则从第一个标题、文件名、周围文件夹、可见日期文本或第一段推断。
不要编造具体的日期、标签、作者或声明。如果某个字段缺失且无法推断,使用清晰的占位符,或者在网站样式允许时省略该字段。
3. 将内容转换为网站样式
通过匹配现有的文章模板和阅读体验来创建新的文章页面。
保留:
- 页眉、导航、页脚、侧边栏和共享外壳。
- 文章排版、间距、元数据布局、标签、返回链接和相关链接。
- 任何特殊的主题语言,如日志条目、田野笔记、卡片、终端/归档框架或简约散文。
- 现有的 CSS 类约定和数据结构。
对于 Markdown:
- 将标题、段落、块引用、列表、任务列表、表格、代码块、链接、脚注、标注和图片转换为语义 HTML。
- 保留代码语言标签(如果可用)。
- 保持图片引用为页面相对路径,仅在需要时复制本地图片。
- 将中文、日文、韩文、带重音的拉丁文和其他非 ASCII 文本保留为可读的 UTF-8。
对于旧 HTML:
- 提取文章正文和元数据。
- 移除旧网站的外壳、分析代码、评论、不相关的导航和源网站标识。
- 将内容重新包装到新网站的文章模板中。
3.5. 保持静态路径兼容性
在添加文章时,从每个生成页面的位置计算路径。不要盲目地将 index.html 中的路径复制到嵌套的文章页面中。
默认规则:
- 新文章页面应使用页面相对链接来引用共享 CSS、JavaScript、字体、图片和导航。
- 如果文章生成在
posts/my-post.html,共享资源通常需要../assets/style.css、../assets/script.js,文章图片例如../assets/images/posts/my-post/figure.png。 - 从根页面到文章的链接通常应为
posts/my-post.html。 - 从文章返回到根页面的链接通常应为
../index.html、../blog.html或../archive/index.html,具体取决于结构。 - 不要引入根绝对路径,如
/assets/...、/posts/...、/data/...或/images/...,除非现有网站有意使用它们,并且用户接受直接file://打开和子路径托管可能失效。 - 使用相同的路径策略更新 JavaScript 生成的链接、搜索结果、标签过滤器、相关文章链接、封面路径、RSS/站点地图条目以及任何数据文件。
- 如果现有网站意外包含了根绝对路径,报告此问题,并优先修复受影响的路径,而不是扩大问题。
避免本地文件获取问题:
- 不要让新添加的文章依赖
fetch()获取本地 JSON/Markdown 来获取文章正文。 - 如果索引是从数据渲染的,确保在 HTML 中保留必要的文章链接,或使用一个支持直接打开预览的相对 JavaScript 数据对象。
4. 处理富内容格式
有意识地在将富内容保留,而不是将其全部扁平化为纯段落。
首先检查当前网站是否已支持:
- 使用 KaTeX、MathJax、自定义 CSS 或原始 TeX 块进行数学渲染。
- 代码高亮、语言标签、复制按钮或终端风格代码框架。
- 表格、响应式表格包装器、脚注、标注、告诫、引用和任务列表。
- 标题锚点、目录、反向链接、相关笔记或章节链接。
- 链接卡片、书签列表、URL 索引页面、引用、参考文献列表或参考书目章节。
- 嵌入式媒体,如视频、音频、PDF、iframe、Mermaid 流程图、Excalidraw/SVG 图表或可下载附件。
当存在现有模式时,遵循它。如果不存在模式,使用简单的语义 HTML,并报告任何需要额外渲染器的功能。
数学和公式:
- 保留来自
$...$、$$...$$、\(...\)、\[...\]或 Word 方程导出的内联和显示数学公式。 - 如果存在,使用网站现有的数学渲染器。
- 如果源包含大量公式且没有渲染器存在,对于纯静态网站,首选本地 KaTeX 集成:将 KaTeX CSS/JS/字体存储在本地 vendor 文件夹下,添加一个小的本地渲染脚本,并且不依赖 CDN。
- 不要静默地向一个原本无依赖的网站添加远程 MathJax/KaTeX 依赖。
- 在数学标记元素内保留原始 TeX 作为后备,然后在浏览器中渲染。如果某个公式渲染失败,可读的 TeX 后备应保持可见,而不是破坏页面。
- 规范化 KaTeX 需要的明显源语法,如 softmax 箭头、
\cdot、\times、意外混入公式的标点符号以及常见的 Q/K/V 表达式。 - 在添加了数学渲染器后,不要让公式密集型文章看起来像代码样式的 TeX 框。
- 确保公式在源代码和浏览器后备中保持可读。
代码块:
- 保留围栏代码的语言名称。
- 对代码块内的 HTML 进行转义。
- 保持长代码行可滚动,而不是破坏页面布局。
- 重用现有的代码块样式、复制按钮和语法高亮约定。
- 不要执行文章中的源代码。
表格:
- 将 Markdown、Word 或 HTML 表格转换为语义表格。
- 将宽表格包裹在网站现有的响应式表格容器中,或添加一个小的本地包装器。
- 保留表头行、对齐意图和标题(如果可用)。
链接、URL 索引和内部引用:
- 保留带有清晰链接文本的外部链接。
- 当目标文章被导入时,将相对链接和 Markdown
.md链接转换为生成的静态 HTML 路径。 - 当目标可以解析时,将 Obsidian wikilinks(如
[[Note]]、[[Note#Heading]]和[[Note|Alias]])转换为普通链接。 - 将未解析的内部链接保留为可见的占位符或纯文本,并报告它们。
- 当网站使用锚点链接或目录时,生成稳定的标题 ID。
- 对于 URL 索引、书签或链接汇总文章,保留列表结构。使用网站现有的链接卡片/列表样式(如果存在);不要发明需要获取远程元数据的预览卡片,除非用户要求。
脚注、引用和参考文献:
- 如果存在,将 Markdown 脚注转换为使用网站现有样式的脚注部分。
- 保留引用标签、参考文献条目和引用链接。
- 如果源文本使用了未解析的引用键(如
[@paper2024]),保持它们可见,并报告引用元数据缺失,除非提供了参考文献文件。
标注、告诫和块类型:
- 将 Obsidian/GitHub 风格的标注(如
> [!NOTE]、> [!TIP]、> [!WARNING]和> [!IMPORTANT])转换为网站最接近的标注/卡片/块引用模式。 - 如果当前网站有复选框样式,将任务列表保留为复选框;否则使用禁用复选框标记或纯列表。
嵌入和附件:
- 对于 PDF、幻灯片、数据集、下载、音频和视频,优先使用清晰的链接或下载卡片,除非网站已嵌入该媒体类型。
- 仅在用户提供时复制本地附件。
- 仅当用户拥有或有意引用远程嵌入时,才保留它们。
- 对于 Mermaid 或图表块,如果存在现有渲染器则使用。如果没有渲染器存在,保留源块并报告,或者仅在实用且合适的情况下转换为静态 SVG/PNG。
5. 处理文章图片和资源
根据当前网站的资产约定处理图片。
首先检查现有文章如何存储和渲染图片:
- 共享资源文件夹,如
assets/images/posts/<slug>/。 - 同位置的文章资源,如
posts/<slug>/images/。 - 数据字段,如
cover、heroImage、thumbnail或images。 - 图形标记、标题、灯箱链接、懒加载、宽度/高度属性和响应式 CSS 类。
优先使用现有模式。如果不存在模式,使用简单的静态约定,例如:
assets/images/posts/<post-slug>/
对于 Markdown 源:
- 从 Markdown 文件的文件夹解析相对图片链接。
- 在需要时将本地图片复制到网站的文章图片文件夹。
- 将 Markdown 图片引用重写为新的相对网站路径。
- 对于嵌套文章页面,在图片路径中包含正确的
../深度。 - 保留 Markdown 中的替代文本(如果存在)。
- 如果源使用了附近的斜体文本、标题属性或 Obsidian 风格的嵌入,转换图片标题。
- 不要让链接指向绝对本地磁盘路径。
对于 Obsidian 笔记:
- 支持常见的嵌入,如
![[image.png]]和相对附件文件夹。 - 在笔记附近搜索可能的附件文件夹,如
attachments/、assets/、images/或库中配置的附件文件夹(如果可见)。 - 将嵌入重写为普通 HTML 图片或图形标记。
对于 Word .docx 源:
- 从文档包中提取嵌入图片或使用可用的文档工具。
- 在可能的情况下保留图片相对于周围文本的顺序。
- 将提取的图片保存在文章图片文件夹下,使用稳定的名称。
- 在可用时使用附近的标题或替代文本作为