web-to-markdown · diff
v0.1.0 to v2.0.0
158 added, 58 removed. Audit A to A.
---
name: web-to-markdown
- description: "Use ONLY when the user explicitly says: 'use the skill web-to-markdown ...' (or 'use a skill web-to-markdown ...'). Converts webpage URLs to clean Markdown by calling the local web2md CLI (Puppeteer + Readability), suitable for JS-rendered pages."
+ description: >
+ 웹페이지를 깨끗한 마크다운으로 변환. JS 렌더링 페이지 지원 (Puppeteer + Readability).
+ 단일/배치 변환, 로그인 필요 페이지, 선택적 콘텐츠 추출.
+ "웹 to 마크다운", "페이지 저장", "web2md" 요청에 실행.
+ /web2md로 실행.
+ triggers:
+ - "web2md"
+ - "web-to-markdown"
+ - "웹 to 마크다운"
+ - "페이지 저장"
+ - "웹페이지 변환"
+ - "URL to markdown"
+ auto_apply: false
+ license: MIT
metadata:
- version: 0.1.0
+ version: "2.0.0"
---
- # web-to-markdown
-
- Convert web pages to clean Markdown by driving a locally installed browser (via `web2md`).
+ # Web to Markdown — 웹페이지 → 마크다운 변환
- ## Hard trigger gate (must enforce)
+ > JS 렌더링 페이지도 깨끗하게 마크다운으로 변환.
+ > Puppeteer + Readability + Turndown 파이프라인.
- This skill MUST NOT be used unless the user explicitly wrote **exactly** a phrase like:
- - `use the skill web-to-markdown ...`
- - `use a skill web-to-markdown ...`
+ ## Quick Start
- If the user did not explicitly request this skill by name, stop and ask them to re-issue the request including: `use the skill web-to-markdown`.
+ ```
+ /web2md https://example.com # 파일로 저장 (자동 이름)
+ /web2md https://example.com --print # 터미널 출력
+ /web2md https://example.com --out ./docs/ref.md # 경로 지정
+ /web2md urls.txt # 배치 변환 (파일에 URL 목록)
+ /web2md https://app.example.com --interactive # 로그인 필요 페이지
+ /web2md https://example.com --selector "main" # 특정 영역만 추출
+ ```
- ## What this skill does
+ **공식 호출명:** `/web2md`
- - Handles JS-rendered pages (Puppeteer → user Chrome).
- - Works best with Chromium-family browsers (Chrome/Chromium/Brave/Edge) via `puppeteer-core`.
- - Extracts main content (Readability).
- - Converts to Markdown (Turndown) with cleaned links and optional YAML frontmatter.
+ ---
- ## Non-goals
+ ## 사전 확인
- - Do not use Playwright or other browser automation stacks; the mechanism is `web2md`.
+ ```bash
+ # web2md 설치 확인
+ command -v web2md || echo "미설치 — 아래 설치 절차 참조"
- ## Inputs you should collect (ask only if missing)
+ # 설치 (프로젝트 존재 시)
+ cd ~/workspace/softaworks/projects/web2md && npm install && npm run build && npm link
+ ```
- - `url` (or a list of URLs)
- - Output preference:
- - Print to stdout (`--print`), OR
- - Save to a file (`--out ./file.md`), OR
- - Save to a directory (`--out ./some-dir/` to auto-name by page title)
- - Optional rendering controls for tricky pages:
- - `--chrome-path <path>` (if Chrome auto-detection fails)
- - `--interactive` (show Chrome and pause so the user can complete human checks/login, then press Enter)
- - `--wait-until load|domcontentloaded|networkidle0|networkidle2`
- - `--wait-for '<css selector>'`
- - `--wait-ms <milliseconds>`
- - `--headful` (debug)
- - `--no-sandbox` (sometimes required in containers/CI)
- - `--user-data-dir <dir>` (login/session; use a dedicated profile directory)
+ ---
## Workflow
- 1) Confirm the user explicitly invoked the skill (`use the skill web-to-markdown`).
- 2) Validate URL(s) start with `http://` or `https://`.
- 3) Ensure `web2md` is installed:
- - Run: `command -v web2md`
- - If missing, instruct the user to install it (assume the project exists at `~/workspace/softaworks/projects/web2md`):
- - `cd ~/workspace/softaworks/projects/web2md && npm install && npm run build && npm link`
- - Or: `cd ~/workspace/softaworks/projects/web2md && npm install && npm run build && npm install -g .`
- 4) Convert:
- - Single URL → file:
- - `web2md '<url>' --out ./page.md`
- - Single URL → auto-named file in directory:
- - `mkdir -p ./out && web2md '<url>' --out ./out/`
- - Human verification / login walls (interactive):
- - `mkdir -p ./out && web2md '<url>' --interactive --user-data-dir ./tmp/web2md-profile --out ./out/`
- - Then: complete the check in the browser window and press Enter in the terminal to continue.
- - Print to stdout:
- - `web2md '<url>' --print`
- - Multiple URLs (batch):
- - Create output dir (e.g. `./out/`) then run one `web2md` command per URL using `--out ./out/`
- 5) Validate output:
- - If writing files, verify they exist and are non-empty (e.g. `ls -la <path>` and `wc -c <path>`).
- 6) Return:
- - The saved file path(s), or the Markdown (stdout mode).
+ ### 1. 단일 URL 변환
- ## Defaults (recommended)
+ ```bash
+ # 자동 이름으로 저장
+ mkdir -p ./out && web2md 'https://docs.example.com/guide' --out ./out/
- - For most pages: `--wait-until networkidle2`
- - For heavy apps: start with `--wait-until domcontentloaded --wait-ms 2000`, then add `--wait-for 'main'` (or another stable selector) if needed.
+ # 지정 파일명으로 저장
+ web2md 'https://docs.example.com/guide' --out ./docs/guide.md
+
+ # 터미널 출력 (파이프에 유용)
+ web2md 'https://docs.example.com/guide' --print
+ ```
+
+ ### 2. 배치 변환 (여러 URL)
+
+ ```bash
+ # URL 목록 파일에서 일괄 변환
+ mkdir -p ./out
+ while IFS= read -r url; do
+ [ -n "$url" ] && web2md "$url" --out ./out/
+ done < urls.txt
+ ```
+
+ ### 3. 로그인 필요 페이지 (Interactive Mode)
+
+ ```bash
+ # 브라우저 창이 열리고, 로그인 완료 후 Enter
+ web2md 'https://app.example.com/dashboard' \
+ --interactive \
+ --user-data-dir ./tmp/web2md-profile \
+ --out ./out/
+
+ # 세션 재사용 (두 번째부터 로그인 불필요)
+ web2md 'https://app.example.com/settings' \
+ --user-data-dir ./tmp/web2md-profile \
+ --out ./out/
+ ```
+
+ ### 4. 까다로운 페이지 처리
+
+ | 상황 | 옵션 |
+ |------|------|
+ | JS 렌더링이 느린 SPA | `--wait-until networkidle2` |
+ | 특정 요소 로드 대기 | `--wait-for 'main article'` |
+ | 추가 대기 시간 필요 | `--wait-ms 3000` |
+ | Chrome 자동 감지 실패 | `--chrome-path /path/to/chrome` |
+ | 컨테이너/CI 환경 | `--no-sandbox` |
+ | 디버깅 | `--headful` |
+
+ ### 5. 선택적 콘텐츠 추출
+
+ ```bash
+ # 본문만 추출 (사이드바, 푸터 제외)
+ web2md 'https://blog.example.com/post' --selector 'article.post-content'
+
+ # 여러 선택자 (첫 번째 매칭)
+ web2md 'https://docs.example.com' --selector 'main, .docs-content, #content'
+ ```
+
+ ---
+
+ ## 출력 품질 개선
+
+ | 문제 | 해결 |
+ |------|------|
+ | 네비게이션/푸터 잔여물 | `--selector`로 범위 한정 |
+ | 이미지 깨진 상대 경로 | 절대 경로로 자동 변환 (내장) |
+ | 코드 블록 언어 미감지 | 수동 확인 후 ``` lang 추가 |
+ | 테이블 깨짐 | GFM 테이블로 변환 (Turndown plugin) |
+ | 불필요한 광고/배너 | Readability가 자동 제거 |
+
+ ### 출력 파일 구조
+
+ ```markdown
+ ---
+ title: Page Title
+ url: https://example.com/page
+ date: 2026-04-16
+ ---
+
+ # Page Title
+
+ 본문 내용...
+ ```
+
+ ---
+
+ ## 검증
+
+ ```bash
+ # 파일 존재 + 크기 확인
+ ls -la ./out/*.md
+
+ # 빈 파일 감지
+ find ./out -name "*.md" -empty
+ ```
+
+ ---
+
+ ## 비교: 언제 어떤 도구를 쓰나?
+
+ | 상황 | 도구 |
+ |------|------|
+ | JS 렌더링 필요한 현대 웹앱 | **web2md** (이 스킬) |
+ | 정적 HTML, 빠른 변환 | `curl` + `pandoc` |
+ | API 문서 → 코드 참고 | Context7 MCP |
+ | 웹 검색 결과 가져오기 | Tavily / Exa MCP |
+
+ ---
+
+ ## 요구사항
+
+ - Node.js 18+
+ - Chrome/Chromium/Edge (Puppeteer가 자동 감지)
+ - `web2md` CLI (`npm link` 또는 `npm install -g`)
+
+ ## Related Files
+
+ | 파일 | 역할 |
+ |------|------|
+ | `skills/pdf/SKILL.md` | PDF 읽기/변환 |
+ | `skills/excel2md/SKILL.md` | 엑셀 읽기/변환 |
+ | `skills/youtube-transcript/SKILL.md` | YouTube 자막 추출 |