这篇文章记录一份可复用的 Markdown 博客文件规范 SKILL。目标是：当我已经写好一篇 .md 文档后，把文件路径交给 Codex，Codex 能调用该 SKILL，把文章整理成当前博客统一格式。

核心要求包括：正文排版统一、标题层级清晰、图片路径尽量本地化、代码块不出现多余横线、表格必须稳定展示。

使用场景

当输入类似下面的请求时，应触发该 SKILL：

使用 Markdown 博客文件规范 SKILL，整理 source/_posts/xxx.md

Codex 需要读取目标 Markdown 文件，保留原始内容含义，在不破坏 front matter、图片、代码块和表格的前提下，把文章整理成博客统一格式。

处理标准

项目 处理要求 验证方式
front matter 保留标题、日期、分类、标签、abbrlink 等关键字段 构建后文章路径不变化
标题 使用 Markdown 标题层级，避免跳级过多 页面目录层级清晰
正文 普通段落保持自然分段，不手动堆 <br> 段落首行缩进、间距统一
图片 优先使用文章资源目录中的本地相对路径 public/post/... 中存在图片
表格 必须使用规范 Markdown 表格或标准 HTML 表格 构建后 <table> 正常显示边框
代码块 使用 fenced code block，并声明语言 代码块无表格横线干扰

SKILL.md 内容

下面内容可以保存为 markdown-blog-format/SKILL.md，作为 Codex 的可复用 Skill。

---
name: markdown-blog-format
description: Normalize existing Markdown blog posts for a Hexo/Sakura personal blog. Use when the user provides a completed .md blog document and asks Codex to standardize formatting, typography, heading hierarchy, indentation, image paths, tables, or code blocks. Especially use when tables must render strictly and code blocks must not show table border lines.
---

# Markdown Blog Format

## Goal

Format an existing Markdown blog post into the blog's standard article style while preserving the author's content, front matter, images, code examples, and table data.

## Required Workflow

1. Read the target `.md` file completely.
2. Preserve YAML front matter unless a field is clearly malformed or missing.
3. Keep the article's original meaning and section order.
4. Normalize Markdown structure, headings, paragraphs, lists, images, tables, and code blocks.
5. Prefer global theme CSS over per-post `<style>` blocks. Do not duplicate local styles if the theme already handles `.entry-content`.
6. Build or validate the site when possible.
7. Report changed files and verification results.

## Front Matter Rules

- Keep `title`, `date`, `categories`, `tags`, `description`, `photos`, and `abbrlink`.
- Do not change `abbrlink` unless the user explicitly asks.
- If `categories` or `tags` are missing, infer conservative values from the existing folder and article topic.
- Do not rewrite unrelated metadata.

## Text Formatting Rules

- Use Markdown headings instead of HTML font headings.
- Keep heading levels coherent: article sections normally start at `##` or `###`, depending on the existing post style.
- Use ordinary paragraphs for prose.
- Avoid manual line breaks with repeated `<br>`.
- Avoid adding inline `style="text-indent:2em"` to every paragraph when global CSS already provides indentation.
- Keep lists as Markdown lists unless nested HTML is required.
- Add blank lines before and after headings, lists, tables, images, and code blocks.

## Image Rules

- Preserve existing `alt` text where possible.
- If an article asset folder exists and contains the matching image, replace remote body image URLs with local article-relative paths.
- For Hexo posts with `post_asset_folder: true`, prefer paths matching the generated article asset directory.
- Do not change `photos`, `avatar`, or other front matter image URLs unless requested.
- Preserve intentional centered image layout.

## Table Rules

Tables are strict. Codex must ensure they render as real tables.

- Use ASCII pipes `|`, not full-width punctuation.
- Every Markdown table must have a header row.
- Every Markdown table must have a separator row.
- Every body row must have the same number of columns as the header.
- Put one blank line before and after each table.
- Escape literal pipes inside cells as `\|`.
- Use `<br>` for short line breaks inside a cell.
- Use `<code>...</code>` for inline code inside cells.
- If a table needs merged cells, complex lists, or multi-paragraph cells, use standard HTML table syntax instead of broken Markdown.

Valid Markdown table:

```markdown
| 项目 | 说明 | 验证 |
| --- | --- | --- |
| 标题 | 层级清晰，不随意跳级 | 目录正常 |
| 表格 | 每行列数一致 | 构建后显示边框 |
```

Valid HTML table for complex content:

```html
<table>
  <thead>
    <tr>
      <th>项目</th>
      <th>说明</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>复杂单元格</td>
      <td>可以使用 <br> 换行，但不要破坏表格结构。</td>
    </tr>
  </tbody>
</table>
```

## Code Block Rules

- Use fenced code blocks with a language tag when possible.
- Do not place Markdown tables inside code blocks unless the article is explaining table syntax.
- Do not let article table CSS affect code-highlighting tables.
- If code blocks show horizontal border lines, ensure theme CSS excludes `.hljs-ln`, `.highlight`, `.highlight-wrap`, and `pre table` from normal table borders.

## Required Theme CSS

If the blog does not already provide global article styles, add or verify equivalent `.entry-content` CSS in the theme:

```css
.entry-content &#123;
  font-size: 16px;
&#125;
.entry-content p &#123;
  line-height: 1.85;
  margin: 8px 0 12px;
  text-indent: 2em;
&#125;
.entry-content p:has(> img:only-child),
.entry-content div[align=center] p,
.entry-content div[align="center"] p &#123;
  text-align: center;
  text-indent: 0;
&#125;
.entry-content table:not(.hljs-ln) &#123;
  width: 100%;
  display: table;
  margin: 16px 0;
  border-collapse: collapse;
  table-layout: auto;
&#125;
.entry-content table:not(.hljs-ln) th,
.entry-content table:not(.hljs-ln) td &#123;
  padding: 8px 10px;
  border: 1px solid #e6e6e6;
  line-height: 1.6;
&#125;
.entry-content pre table,
.entry-content .highlight table,
.entry-content .highlight-wrap table,
.entry-content table.hljs-ln &#123;
  width: auto;
  margin: 0;
  border-collapse: separate;
&#125;
.entry-content pre th,
.entry-content pre td,
.entry-content .highlight th,
.entry-content .highlight td,
.entry-content .highlight-wrap th,
.entry-content .highlight-wrap td,
.entry-content table.hljs-ln th,
.entry-content table.hljs-ln td &#123;
  padding: 0;
  border: 0;
  background: transparent;
  line-height: inherit;
&#125;
```

## Validation Checklist

- Run the blog build command when available, such as `npm run build`.
- Confirm the generated HTML exists under `public/post/`.
- Search the generated HTML for unexpected remote image URLs if local replacement was requested.
- Confirm table syntax has consistent column counts before building.
- Confirm code blocks do not inherit normal table borders.
- Summarize exact files changed and any skipped validation.

执行时的重点

这个 SKILL 的关键不是把文章改得更花哨，而是让每篇文章都能稳定渲染。尤其是表格，不允许出现“源文件看着像表格，页面上却散掉”的情况。

检查点 不合格表现 修正方式
表格分隔行缺失 页面显示成普通文本 添加 | --- | --- | 分隔行
每行列数不一致 表格错位或断裂 补齐缺失单元格
单元格中包含 | 被误判为新列 写成 \|
代码块出现横线 表格边框样式污染代码表 CSS 排除 .hljs-ln 和 pre table
图片段落缩进 图片整体偏右 图片段落取消 text-indent

总结

后续如果要让 Codex 按统一规范整理博客文章，只需要把目标 .md 文件路径交给它，并明确要求使用这个 Markdown 博客文件规范 SKILL。Codex 应优先保留文章内容本身，只处理排版、路径、表格、代码块和渲染稳定性问题。

赏