web-to-markdown

Name: web-to-markdown
Author: bear2u

github.com/bear2u文档处理93545 次安装18 周前更新

代码仓库

关于 web-to-markdown

web-to-markdown 是将网页内容转换并保存为 Markdown 的技能，适用于网页归档和资料整理。它提供普通、AI 优化和双版本模式，并可在页面内容不足时使用 Playwright 作为备用方案。

主要功能

01网页内容转换为 Markdown
02提供普通与 AI 优化模式
03同时生成原文和优化版本
04支持多个 URL 和指定章节
05内容不足时可改用 Playwright

适用场景

01归档网页或博客文章
02保存供 AI 处理的文档资料
03批量转换文档页面
04提取网页中的指定章节

MCP 相关

该技能说明可在动态网页内容不足时，选择通过 MCP Playwright 服务器调用浏览器工具获取页面。MCP Playwright 是可选的备用方式。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/bear2u/my-skills --skill web-to-markdown

安装后在 Claude Code 中输入/web-to-markdown确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

AI_OPTIMIZATION.md

EXAMPLES.md

QUICKSTART.md

README.md

samples/

claudecode-best-practices.context.md

claudecode-best-practices.md

详细介绍

网页转 Markdown

输入网页 URL，将页面内容转换为 Markdown 格式并保存。

适用场景

遇到以下请求时使用此技能：

“把网页转换成 Markdown”
“把这个 URL 保存为 Markdown”
“把网站内容制作成 Markdown 文件”
“归档网页”
“把博客文章保存为 Markdown”
“转换成便于 AI 阅读的格式”（AI 优化模式）
“转换成适合用作上下文的格式”（AI 优化模式）
“原版和 AI 优化版都生成”（双模式）⭐ NEW

核心工作流程

Step 1：获取 URL

请用户提供要转换的网页 URL。

示例：

Claude: 변환하실 웹페이지의 URL을 입력해주세요.
User: https://example.com/article

重要：

URL 必须以 http:// 或 https:// 开头
HTTP URL 会自动升级为 HTTPS
无效的 URL 会返回错误

Step 2：选择转换模式

分析用户的请求，选择合适的转换模式。

转换模式：

普通模式（默认）：将网页转换为易于阅读的 Markdown
AI 优化模式：转换为适合 AI Agent 用作上下文的格式
双模式 ⭐ NEW：生成原版 + AI 优化版两个文件

自动检测关键词：

“便于 AI 阅读”“用作上下文”“用于 AI 学习” → AI 优化模式
“原版和”“两个都要”“2 个”“both”“也保存原版” → 双模式
其他 → 普通模式

示例 1（AI 优化）：

User: https://example.com/article AI가 읽기 좋게 변환해줘
Claude: AI 최적화 모드로 변환하겠습니다. 구조화된 포맷과 메타데이터를 추가합니다.

示例 2（双模式）：

User: https://example.com/article 원본이랑 AI 최적화 버전 둘 다 만들어줘
Claude: 듀얼 모드로 변환하겠습니다.
- 원본 마크다운 (article.md)
- AI 최적화 버전 (article.context.md)
2개 파일을 생성합니다.

Step 3：确认保存选项

向用户确认保存位置和文件名。

示例：

Claude: 마크다운 파일을 어디에 저장할까요?
옵션:
1. 현재 디렉토리 (./)
2. 특정 경로 지정
3. 파일로 저장하지 않고 내용만 보기

파일명은? (기본값: webpage.md)
User: 현재 디렉토리에 article.md로 저장해줘

Step 4：获取网页并转换

使用 WebFetch 工具获取网页并转换为 Markdown。

普通模式提示词

url = "https://example.com/article"
prompt = "웹페이지의 전체 내용을 마크다운 형식으로 변환해주세요. 제목, 본문, 링크, 이미지 등 모든 요소를 포함하되, 불필요한 네비게이션이나 광고는 제외해주세요."

AI 优化模式提示词（CRITICAL）

url = "https://example.com/article"
prompt = """이 웹페이지를 AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환해주세요:

**필수 구조:**

1. **프론트매터 (YAML 형식)**
---
title: "페이지 제목"
url: "원본 URL"
author: "작성자 (있는 경우)"
date: "발행일 (있는 경우)"
word_count: 대략적인 단어 수
topics: ["주제1", "주제2", "주제3"]
summary: |
  이 글의 핵심을 3-5줄로 요약
  AI가 빠르게 파악할 수 있도록
main_points:
  - 핵심 포인트 1
  - 핵심 포인트 2
  - 핵심 포인트 3
content_type: "tutorial|guide|article|documentation|news|blog"
difficulty: "beginner|intermediate|advanced"
---

2. **본문 구조**
# [원본 제목]

## 핵심 요약
[3-5줄로 이 글이 무엇을 다루는지 명확하게]

## 주요 내용
[명확한 계층 구조로 섹션 구분, H2/H3 사용]

### 섹션 1
[내용]

### 섹션 2
[내용]

## 핵심 인사이트
- 인사이트 1
- 인사이트 2
- 인사이트 3

## 실용적 적용
[이 내용을 어떻게 활용할 수 있는지]

## 관련 리소스
[링크가 있다면 설명과 함께]

## 결론
[마무리 요약]

**변환 규칙:**
- 광고, 네비게이션, 푸터, 사이드바 완전 제거
- 코드 블록은 언어 명시 (```python, ```javascript 등)
- 링크는 [설명](URL) 형식으로 명확하게
- 이미지는 ![설명](URL) 형식으로
- 불필요한 수식어 제거, 간결하게
- 리스트는 명확한 bullet points로
- 중요한 개념은 **굵게** 강조

**최종 목표:**
AI가 이 문서를 읽고 핵심을 3초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""

重要：

WebFetch 会自动将 HTML 转换为 Markdown
会应用 15 分钟缓存，重复请求同一 URL 时速度更快
如果发生重定向，则使用新的 URL 重新请求
AI 优化模式可节省 30-50% 的令牌，并使结构更加清晰

Step 5：保存 Markdown

将转换后的 Markdown 保存到文件。

# Write 도구를 사용하여 파일 저장
Write {
  file_path: "/Users/symverse/workspaces-skill-test/my-skills-hub/article.md"
  content: "[변환된 마크다운 내용]"
}

AI 优化模式的推荐文件名：

普通：article.md
AI 优化：article-ai-optimized.md 或 article.context.md

Step 6：查看结果

向用户显示保存的文件路径和简要统计信息。

✅ 웹페이지를 마크다운으로 변환했습니다!

📄 파일: article.md
📍 경로: /Users/symverse/workspaces-skill-test/my-skills-hub/article.md
📊 크기: 약 1,234 글자

[View file](computer:///Users/symverse/workspaces-skill-test/my-skills-hub/article.md)

双模式工作流程 ⭐ NEW

双模式会同时生成原版 Markdown 和 AI 优化版。这样可以同时获得供人阅读的资料和供 AI 处理的资料。

双模式 Step 1：确认 URL 和文件名

User: https://react.dev/reference/react/useState 원본이랑 AI 최적화 버전 둘 다 만들어줘

Claude: 듀얼 모드로 변환하겠습니다.
기본 파일명은? (기본: webpage)

双模式 Step 2：生成原版 Markdown

使用普通模式提示词，通过 WebFetch 生成原版 Markdown。

url = "https://react.dev/reference/react/useState"
prompt = "웹페이지의 전체 내용을 마크다운 형식으로 변환해주세요. 제목, 본문, 링크, 이미지 등 모든 요소를 포함하되, 불필요한 네비게이션이나 광고는 제외해주세요."

保存原版文件：

Write {
  file_path: "/path/to/useState.md"
  content: "[원본 마크다운 내용]"
}

双模式 Step 3：生成 AI 优化版

CRITICAL：针对同一 URL，再次使用 AI 优化提示词调用 WebFetch。

url = "https://react.dev/reference/react/useState"  # 동일한 URL
prompt = """이 웹페이지를 AI 에이전트가 컨텍스트로 활용하기 최적화된 형태로 변환해주세요:

**필수 구조:**

1. **프론트매터 (YAML 형식)**
---
title: "페이지 제목"
url: "원본 URL"
author: "작성자 (있는 경우)"
date: "발행일 (있는 경우)"
word_count: 대략적인 단어 수
topics: ["주제1", "주제2", "주제3"]
summary: |
  이 글의 핵심을 3-5줄로 요약
  AI가 빠르게 파악할 수 있도록
main_points:
  - 핵심 포인트 1
  - 핵심 포인트 2
  - 핵심 포인트 3
content_type: "tutorial|guide|article|documentation|news|blog"
difficulty: "beginner|intermediate|advanced"
---

2. **본문 구조**
# [원본 제목]

## 핵심 요약
[3-5줄로 이 글이 무엇을 다루는지 명확하게]

## 주요 내용
[명확한 계층 구조로 섹션 구분, H2/H3 사용]

### 섹션 1
[내용]

### 섹션 2
[내용]

## 핵심 인사이트
- 인사이트 1
- 인사이트 2
- 인사이트 3

## 실용적 적용
[이 내용을 어떻게 활용할 수 있는지]

## 관련 리소스
[링크가 있다면 설명과 함께]

## 결론
[마무리 요약]

**변환 규칙:**
- 광고, 네비게이션, 푸터, 사이드바 완전 제거
- 코드 블록은 언어 명시 (```python, ```javascript 등)
- 링크는 [설명](URL) 형식으로 명확하게
- 이미지는 ![설명](URL) 형식으로
- 불필요한 수식어 제거, 간결하게
- 리스트는 명확한 bullet points로
- 중요한 개념은 **굵게** 강조

**최종 목표:**
AI가 이 문서를 읽고 핵심을 3초 안에 파악하고,
사용자의 질문에 정확하게 답변할 수 있도록 최적화
"""

保存 AI 优化文件：

Write {
  file_path: "/path/to/useState.context.md"
  content: "[AI 최적화 마크다운 내용]"
}

双模式 Step 4：总结结果

向用户显示生成的 2 个文件。

✅ 듀얼 모드 변환 완료! 2개 파일이 생성되었습니다.

📄 원본 마크다운:
- 파일: useState.md
- 경로: /path/to/useState.md
- 크기: 약 3,500 글자
- 용도: 사람이 읽기 좋은 원본 보존

[View file](computer:///path/to/useState.md)

📄 AI 최적화 버전:
- 파일: useState.context.md
- 경로: /path/to/useState.context.md
- 크기: 약 2,100 글자 (40% 절감)
- 용도: AI 컨텍스트로 활용

[View file](computer:///path/to/useState.context.md)

💡 팁:
- 원본(.md)은 사람이 읽을 때 사용
- AI 최적화(.context.md)는 RAG 시스템이나 AI 에이전트 컨텍스트로 사용

双模式文件命名规则

模式 1：通过扩展名区分（推荐）

原版：article.md
AI 优化版：article.context.md

模式 2：通过后缀区分

原版：article.md
AI 优化版：article-ai-optimized.md

模式 3：通过文件夹区分

/docs
├── original/
│   └── article.md
└── optimized/
    └── article.md

双模式的优点

保留原版：供人阅读的资料保持原样
提高 AI 效率：AI 版可节省令牌并进行结构化处理
按用途区分：根据目的使用合适的文件
备份效果：同时备份两种形式
便于比较：可以对比分析原版和优化版

双模式使用场景

场景 1：归档技术文档

User: 이 React 문서들 원본이랑 AI 최적화 버전 둘 다 만들어줘
- https://react.dev/reference/react/useState
- https://react.dev/reference/react/useEffect

Claude: 듀얼 모드로 4개 파일 생성합니다.
- useState.md (원본)
- useState.context.md (AI 최적화)
- useEffect.md (원본)
- useEffect.context.md (AI 최적화)

场景 2：备份博客文章

User: 내 블로그 글을 백업하는데 원본도 저장하고 AI가 읽을 수 있는 버전도 만들어줘

Claude: 듀얼 모드로 변환하겠습니다.
- 원본: 사람이 다시 읽을 때
- AI 최적화: 나중에 AI에게 질문할 때

场景 3：构建学习资料

User: 이 튜토리얼들을 둘 다 버전으로 저장해줘

Claude:
study-materials/
├── original/          # 사람이 학습용
│   ├── intro.md
│   └── advanced.md
└── ai-optimized/      # AI 질문 답변용
    ├── intro.context.md
    └── advanced.context.md

高级选项

批量转换多个 URL

可以一次转换多个网页。

示例：

User: 이 URL들을 전부 마크다운으로 저장해줘
- https://example.com/article1
- https://example.com/article2
- https://example.com/article3

Claude: 3개의 웹페이지를 변환하겠습니다. 파일명은 자동으로 생성할까요, 아니면 각각 지정하시겠어요?
User: 자동으로

Claude: [각 URL을 순차적으로 변환하여 article1.md, article2.md, article3.md로 저장]

仅提取特定部分

可以仅提取网页的特定部分。

示例：

User: https://example.com/docs 에서 "Installation" 섹션만 마크다운으로 저장해줘

Claude: [WebFetch 프롬프트에 "Installation 섹션만 추출"을 명시하여 해당 부분만 변환]

自定义 Markdown 格式

可以指定转换时使用的 Markdown 样式。

示例：

User: 이 블로그 글을 마크다운으로 변환하되, 모든 제목을 H2(##)로 시작하고 코드 블록은 syntax highlighting 포함해줘

Claude: [WebFetch 프롬프트에 포맷 요구사항을 명시]

错误处理

URL 无效

User: htp://wrong-url
Claude: ❌ 올바르지 않은 URL입니다. http:// 또는 https://로 시작하는 전체 URL을 입력해주세요.

无法访问页面

Claude: ❌ 해당 웹페이지에 접근할 수 없습니다.
- 페이지가 삭제되었거나
- 접근 권한이 필요하거나
- 네트워크 오류가 발생했을 수 있습니다.

文件保存错误

Claude: ❌ 파일을 저장할 수 없습니다.
- 경로가 올바른지 확인해주세요
- 쓰기 권한이 있는지 확인해주세요
- 디렉토리가 존재하는지 확인해주세요

工作流程示例

示例 1：转换单个网页

User: https://docs.python.org/3/tutorial/index.html 이거 마크다운으로 저장해줘

Claude: 파이썬 튜토리얼 페이지를 마크다운으로 변환하겠습니다.
파일명을 어떻게 할까요? (기본: webpage.md)

User: python-tutorial.md

Claude: [WebFetch로 페이지 가져오기]
Claude: [마크다운으로 변환]
Claude: [파일 저장]

✅ 웹페이지를 마크다운으로 변환했습니다!

📄 파일: python-tutorial.md
📍 경로: /Users/symverse/workspaces-skill-test/my-skills-hub/python-tutorial.md
📊 크기: 약 15,234 글자

[View file](computer:///Users/symverse/workspaces-skill-test/my-skills-hub/python-tutorial.md)

示例 2：归档博客文章

User: 이 블로그 글들을 전부 마크다운으로 저장해서 아카이브 폴더에 넣어줘
- https://blog.example.com/post1
- https://blog.example.com/post2

Claude: 2개의 블로그 글을 archive 폴더에 저장하겠습니다.

[디렉토리 생성]
[각 URL을 순차적으로 변환]

✅ 2개의 웹페이지를 변환했습니다!

📁 archive/
  ├── post1.md
  └── post2.md

示例 3：仅查看文档内容（不保存）

User: https://github.com/anthropics/claude-code 이 페이지 내용을 마크다운으로 보여줘만 하고 저장은 하지마

Claude: [WebFetch로 페이지 가져오기]

다음은 해당 페이지의 마크다운 변환 내용입니다:

---
# Claude Code

Claude Code is an official CLI...

[전체 내용 출력]
---

저장하지 않고 내용만 보여드렸습니다.

技术详情

使用 WebFetch

自动转换：自动将 HTML 转换为 Markdown
缓存：15 分钟自动清理缓存
重定向处理：自动使用新的 URL 重新请求

Markdown 转换质量

WebFetch 会将以下元素转换为 Markdown：

标题（H1-H6）
段落和文本格式（bold、italic、code）
链接和图片
列表（有序、无序）
代码块
引用
表格

不必要的元素会被排除：

导航菜单
页脚
广告
侧边栏（视情况而定）

文件保存

默认路径：当前工作目录
文件扩展名：.md
编码：UTF-8
覆盖：如果文件已存在，会在确认后覆盖

最佳实践

使用清晰的文件名：使用能准确描述内容的文件名
整理文件夹结构：转换多个页面时，按主题整理到不同文件夹
检查 URL：转换前确认 URL 正确
注意版权：尊重网页内容的版权
仅用于个人归档：主要用作个人参考资料

动态内容处理

问题：JavaScript 渲染的页面

WebFetch 只能获取静态 HTML，因此对于 React、Vue、Next.js 等通过 JavaScript 渲染的页面，可能会返回空内容。

症状：

转换后的 Markdown 几乎为空
只显示 “Loading...” 之类的占位文本
缺少核心内容

解决方案：Playwright 回退方案

如果 WebFetch 获取的内容为空或不完整，请使用 AskUserQuestion 询问用户是否使用 Playwright。

Step 1：验证 WebFetch 结果

# WebFetch로 가져온 마크다운 내용 확인
if len(markdown_content.strip()) < 500:  # 너무 짧으면
    # 동적 콘텐츠일 가능성 높음

第 2 步：询问用户

使用 AskUserQuestion：

AskUserQuestion {
  questions: [
    {
      question: "이 페이지는 동적 콘텐츠(JavaScript)를 사용하는 것 같습니다. Playwright를 실행해서 브라우저로 데이터를 가져올까요?",
      header: "Playwright",
      multiSelect: false,
      options: [
        {
          label: "Yes, Playwright로 재시도",
          description: "Chromium 브라우저를 실행해서 JavaScript 렌더링 후 콘텐츠 가져오기 (느림, 정확함)"
        },
        {
          label: "No, 현재 내용만 저장",
          description: "WebFetch 결과만 저장 (빠름, 불완전할 수 있음)"
        }
      ]
    }
  ]
}

第 3-A 步：使用 MCP Playwright（推荐 ⭐）

**准备工作：**必须已安装 MCP Playwright 服务。

# 최초 1회만 설치
npx @modelcontextprotocol/server-playwright

在技能中使用：

// 1. 페이지 이동
mcp__playwright__navigate({
  url: "https://example.com"
})

// 2. JavaScript 렌더링 대기
mcp__playwright__waitForLoadState({
  state: "networkidle"
})

// 3. HTML 콘텐츠 가져오기
const htmlContent = mcp__playwright__getContent()

// 4. 마크다운으로 변환 (WebFetch 프롬프트 재사용)
// htmlContent를 마크다운으로 변환하는 로직

第 3-B 步：使用 Node Playwright（替代方案）

如果没有 MCP Playwright，可直接使用 Node.js 运行：

# Playwright 스크립트 실행
node << 'EOF'
const playwright = require('playwright');

(async () => {
  const browser = await playwright.chromium.launch({ headless: true });
  const page = await browser.newPage();

  console.log('⏳ 페이지 로딩 중...');
  await page.goto('https://example.com', { waitUntil: 'networkidle' });

  console.log('⏳ JavaScript 렌더링 대기 중...');
  await page.waitForTimeout(3000); // 3초 대기

  const content = await page.content();
  console.log(content);

  await browser.close();
})();
EOF

将输出保存到文件：

# HTML을 임시 파일로 저장
node playwright-script.js > temp.html

# 이제 이 HTML을 마크다운으로 변환
# (WebFetch 대신 직접 변환 로직 사용)

第 4 步：转换并保存

将通过 Playwright 获取的 HTML 转换为 Markdown。

选项 A：重用 WebFetch 提示词

将通过 Playwright 获取的完整 HTML 放入 WebFetch 提示词中，转换为 Markdown。

选项 B：直接解析

使用 HTML → Markdown 转换库（例如 turndown、html-to-markdown）

工作流摘要

1. WebFetch로 시도 (빠름)
   ↓
2. 결과 검증 (내용이 충분한가?)
   ↓ NO
3. AskUserQuestion (Playwright 사용할까요?)
   ↓ YES
4. Playwright로 재시도
   ├─ MCP Playwright (권장) 또는
   └─ Node Playwright (대안)
   ↓
5. 마크다운 변환 및 저장

MCP Playwright 与 Node Playwright 对比

项目	MCP Playwright ⭐	Node Playwright
安装	需要安装 MCP 服务	`npm install playwright`
调用方式	调用 MCP 工具	执行 Bash 命令
会话管理	自动	手动（编写脚本）
错误处理	简洁	复杂
Claude Code 集成	原生支持	间接运行
推荐度	⭐⭐⭐⭐⭐	⭐⭐⭐

实战示例

场景：转换 React 官方文档

User: https://react.dev/reference/react/useState 마크다운으로 변환해줘

Claude: [WebFetch 시도]
Claude: ⚠️ 이 페이지는 JavaScript로 렌더링되는 것 같습니다.
        내용이 거의 비어있네요.

[AskUserQuestion 호출]

User: Yes, Playwright로 재시도

Claude: ⏳ Playwright로 페이지 로딩 중...
Claude: ✅ JavaScript 렌더링 완료
Claude: ✅ 마크다운 변환 완료

📄 파일: useState.md
📍 경로: /path/to/useState.md
📊 크기: 약 5,234 글자 (전체 콘텐츠 포함)

附加选项：自动检测模式

面向高级用户，可支持 --auto-playwright 标志：

User: https://react.dev/reference/react/useState 마크다운으로 변환해줘 (자동으로 Playwright 사용해도 돼)

Claude: [WebFetch 시도]
Claude: [자동으로 Playwright 폴백]
Claude: ✅ 마크다운 변환 완료

提示

长文档：非常长的网页可能会包含摘要
动态内容：Playwright 可以处理通过 JavaScript 渲染的内容 ⭐ 新增
图片：图片将以原始 URL 链接的形式包含（不会下载）
重新转换：在 15 分钟内再次请求相同的 URL 时，将使用缓存版本
MCP Playwright：对于包含大量动态内容的网页，建议安装 MCP Playwright 服务

支持 Markdown

登录后评论

基本信息

作者: bear2u
仓库: bear2u/my-skills
分类: 文档处理
安装次数: 45
GitHub Stars: 935

报告问题