Skip to content

zach22-1999/generic-skills / skills/zach-md-html

zach-md-html

Verified

已降级的 Markdown→HTML 兼容转换器。仅当用户明确要求“使用 zach-md-html”、或明确说“不要重组内容,只把现成 Markdown 机械转换成 HTML/套用旧主题”时使用。不要因为用户只说“输出成 HTML”“生成 HTML 报告”“把日常报告做成 HTML”“数据报告/交付报告”而触发;这些任务应由模型从原始资料直接组织并生成自包含 HTML。此 Skill 不负责数据可视化、工作面、自由设计、万物转 md、html 转 md 或 md 转 docx。

references/markitdown-cookbook.md

View on GitHub
# markitdown cookbook — 各文件类型的转换最佳实践

> 这个 cookbook 是能力1(万物→md)的实战参考。脚本 `scripts/any_to_md.py` 包装了下面所有用法。

## 安装

```bash
# 推荐:一次到位
pip install 'markitdown[all]'

# 可选 extras(按需选)
# pdf docx pptx xlsx xls outlook audio-transcription youtube-transcription az-doc-intel
pip install 'markitdown[pdf,docx,pptx,xlsx]'
```

需要 Python ≥ 3.10。

## 各类型 cookbook

### PDF

```bash
python scripts/any_to_md.py file.pdf -o out.md
```

**适用场景**:原生PDF(含可选文本层)。

**坑与降级**:
- 扫描PDF(图片PDF)→ 默认输出几乎为空,必须挂 LLM 或 Azure Document Intelligence
- 复杂表格(合并单元格、嵌套)→ 单元格语义可能丢失
- 带图表/图片的PDF → 图片不会被OCR,只保留文件名

**降级路径**:
```bash
# 挂 LLM 描述图片(要 OPENAI_API_KEY)
python scripts/any_to_md.py file.pdf --llm-describe

# 挂 Azure Document Intelligence(高保真扫描件)
python scripts/any_to_md.py file.pdf \
  --azure-doc-intel "https://xxx.cognitiveservices.azure.com/"
```

### DOCX

```bash
python scripts/any_to_md.py document.docx -o out.md
```

**质量**:对纯文本/标准排版的Word文档接近无损。Heading 1/2/3 能正确映射成 `#` `##` `###`。

**坑**:
- 文本框、SmartArt、复杂浮动布局 → 会被扁平化或丢失
- 修订标记、批注 → 默认不保留
- 嵌入的图片 → 提取出文件名占位,不内嵌

### PPTX

```bash
python scripts/any_to_md.py deck.pptx -o out.md
```

**输出结构**:每张幻灯片 = 一个 `## Slide N` 段落,包含文字 + speaker notes。

**坑**:
- 动画、过渡、布局完全丢失
- 图表数据丢失(只保留chart的标题)
- 用作"AI消化PPT内容"OK,用作"还原幻灯片"则不够

### XLSX / XLS

```bash
python scripts/any_to_md.py spreadsheet.xlsx -o out.md
```

**输出**:每个worksheet 转成 markdown table。

**坑**:
- 公式不会被evaluate,只看cell的当前值
- 合并单元格 → 拆开
- 数据透视表、图表 → 丢失

**替代**:复杂Excel分析用 `xlsx` skill 或 pandas 直接处理,这里只用于"提取干净文本喂AI"。

### HTML

```bash
python scripts/any_to_md.py page.html -o out.md
```

**质量**:对简单HTML(带article/section/p/h1-6/ul/ol)很好。复杂页面(带nav/aside/广告)会保留所有HTML结构产生噪声。

**推荐**:HTML转md优先用**能力3**(`html_to_md.py`),它有 trafilatura 做正文提取,自动去噪。

### 图片(jpg/png/gif)

```bash
# 不挂LLM:只提取EXIF和文件名
python scripts/any_to_md.py photo.jpg

# 挂LLM:让模型描述图片内容
python scripts/any_to_md.py photo.jpg --llm-describe
```

需要 `OPENAI_API_KEY` 和 `pip install openai`。

### 音频(mp3/wav/m4a)

```bash
# 需要先装 audio-transcription extra
pip install 'markitdown[audio-transcription]'

python scripts/any_to_md.py recording.mp3 -o transcript.md
```

底层用 `pydub` + `speech_recognition`,离线可用,但准确度随音质变化大。

**替代方案**:更高质量的方案通常是专门的字幕转写工具,准确度更高,特别是中文长音频。

### YouTube URL

```bash
# 需要先装 youtube-transcription extra
pip install 'markitdown[youtube-transcription]'

python scripts/any_to_md.py "https://www.youtube.com/watch?v=xxx" -o video.md
```

会自动抓取YouTube字幕(如有)。**没有字幕的视频会失败**,需要降级到 `gemini-video` skill。

### EPub

```bash
python scripts/any_to_md.py book.epub -o book.md
```

按章节切分输出,每章一个 H1/H2。封面图、文内插图丢失。

### ZIP

```bash
python scripts/any_to_md.py archive.zip -o archive.md
```

**行为**:递归解包,每个内部文件按其类型转md,按目录结构组织。

### Outlook .msg

```bash
pip install 'markitdown[outlook]'
python scripts/any_to_md.py email.msg -o email.md
```

提取主题/发件人/收件人/正文/附件名。附件本身不会被转换。

## 一条龙工作流

```bash
# PDF白皮书 → md → 精美阅读html
python scripts/any_to_md.py whitepaper.pdf -o wp.md
python scripts/md_to_html.py wp.md --theme report -o wp.html

# YouTube视频 → md脚本 → 文章博客
python scripts/any_to_md.py "https://youtube.com/watch?v=xxx" -o talk.md
# 编辑 talk.md,改写成文章...
python scripts/md_to_html.py talk.md --theme article -o blog.html
```

## 何时不用 markitdown

| 任务 | 用什么 |
|------|--------|
| 需要保留布局精度(不只是文本) | 直接用 PDF reader / docx 库 / pptx skill |
| 需要OCR扫描件 | 挂 LLM 或 Azure DocIntel;或专门 OCR 工具(Tesseract/PaddleOCR) |
| 需要分析数据(不是提取文本) | xlsx skill 或 pandas |
| 中文音视频转写 | 专门字幕转写工具或视频理解工具 |
| HTML 网页(带噪声) | 直接用本skill的能力3(`html_to_md.py`) |

## 已知的版本变化

- v0.1.5(2026-02-20):内存内转换、PDF表格对齐改善、插件架构开放
- v0.1.x 之前:表格还原差,建议升级到最新

```bash
# 检查当前版本
pip show markitdown | grep Version

# 升级
pip install -U 'markitdown[all]'
```
canvas-designanthropics/skillsCreate beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists' work to avoid copyright violations.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
docxanthropics/skillsUse this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', '.dotx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx or .dotx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pdfanthropics/skillsUse this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
pptxanthropics/skillsUse this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions "deck," "slides," "presentation," or references a .pptx or .potx filename, regardless of what they plan to do with the content afterward. If a .pptx or .potx file needs to be opened, created, or touched, use this skill.Stars: 198kUpdated Claude CodeCodexVerifiedInstall