tuzi-url-to-markdown

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

URL to Markdown

URL 转 Markdown

Fetches any URL via Chrome CDP and converts HTML to clean markdown.

通过 Chrome CDP 获取任意URL并将HTML转换为简洁的Markdown格式。

Script Directory

脚本目录

Important: All scripts are located in the

scripts/

subdirectory of this skill.

Agent Execution Instructions:

Determine this SKILL.md file's directory path as
```
SKILL_DIR
```
Script path =
```
${SKILL_DIR}/scripts/<script-name>.ts
```
Replace all
```
${SKILL_DIR}
```
in this document with the actual path

Script Reference:

Script	Purpose
`scripts/main.ts`	CLI entry point for URL fetching

重要提示：所有脚本均位于此skill的

scripts/

子目录中。

Agent执行说明：

确定此SKILL.md文件的目录路径为
```
SKILL_DIR
```
脚本路径 =
```
${SKILL_DIR}/scripts/<script-name>.ts
```
将本文档中所有
```
${SKILL_DIR}
```
替换为实际路径

脚本参考：

脚本	用途
`scripts/main.ts`	URL抓取的CLI入口

Preferences (EXTEND.md)

偏好设置（EXTEND.md）

Use Bash to check EXTEND.md existence (priority order):

bash

undefined

使用Bash检查EXTEND.md是否存在（优先级顺序）：

bash

undefined

Check project-level first

先检查项目级

test -f .tuzi-skills/tuzi-url-to-markdown/EXTEND.md && echo "project"

Then user-level (cross-platform: $HOME works on macOS/Linux/WSL)

然后检查用户级（跨平台：$HOME在macOS/Linux/WSL均适用）

test -f "$HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md" && echo "user"


┌────────────────────────────────────────────────────────┬───────────────────┐
│                          Path                          │     Location      │
├────────────────────────────────────────────────────────┼───────────────────┤
│ .tuzi-skills/tuzi-url-to-markdown/EXTEND.md          │ Project directory │
├────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md    │ User home         │
└────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  Result   │                                  Action                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Found     │ Read, parse, apply settings                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ Not found │ **MUST** run first-time setup (see below) — do NOT silently create defaults │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md Supports**: Download media by default | Default output directory | Default capture mode | Timeout settings

test -f "$HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md" && echo "user"


┌────────────────────────────────────────────────────────┬───────────────────┐
│                          路径                          │     位置      │
├────────────────────────────────────────────────────────┼───────────────────┤
│ .tuzi-skills/tuzi-url-to-markdown/EXTEND.md          │ 项目目录 │
├────────────────────────────────────────────────────────┼───────────────────┤
│ $HOME/.tuzi-skills/tuzi-url-to-markdown/EXTEND.md    │ 用户主目录         │
└────────────────────────────────────────────────────────┴───────────────────┘

┌───────────┬───────────────────────────────────────────────────────────────────────────┐
│  结果   │                                  操作                                   │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 已找到     │ 读取、解析并应用设置                                               │
├───────────┼───────────────────────────────────────────────────────────────────────────┤
│ 未找到 │ **必须**运行首次设置（见下文）——请勿静默创建默认设置 │
└───────────┴───────────────────────────────────────────────────────────────────────────┘

**EXTEND.md支持**：默认下载媒体文件 | 默认输出目录 | 默认抓取模式 | 超时设置

First-Time Setup (BLOCKING)

首次设置（阻塞操作）

CRITICAL: When EXTEND.md is not found, you MUST use
AskUserQuestion
to ask the user for their preferences before creating EXTEND.md. NEVER create EXTEND.md with defaults without asking. This is a BLOCKING operation — do NOT proceed with any conversion until setup is complete.

Use

AskUserQuestion

with ALL questions in ONE call:

Question 1 — header: "Media", question: "How to handle images and videos in pages?"

"Ask each time (Recommended)" — After saving markdown, ask whether to download media
"Always download" — Always download media to local imgs/ and videos/ directories
"Never download" — Keep original remote URLs in markdown

Question 2 — header: "Output", question: "Default output directory?"

"url-to-markdown (Recommended)" — Save to ./url-to-markdown/{domain}/{slug}.md
(User may choose "Other" to type a custom path)

Question 3 — header: "Save", question: "Where to save preferences?"

"User (Recommended)" — ~/.tuzi-skills/ (all projects)
"Project" — .tuzi-skills/ (this project only)

After user answers, create EXTEND.md at the chosen location, confirm "Preferences saved to [path]", then continue.

Full reference: references/config/first-time-setup.md

关键提示：当未找到EXTEND.md时，你必须使用
AskUserQuestion
询问用户偏好后再创建EXTEND.md。绝不要在未询问的情况下使用默认值创建EXTEND.md。这是一个阻塞操作——在设置完成前请勿进行任何转换操作。

一次性调用

AskUserQuestion

提出所有问题：

问题1 — 标题："媒体文件"，问题："如何处理页面中的图片和视频？"

"每次询问（推荐）" — 保存Markdown后，询问是否下载媒体文件
"始终下载" — 始终将媒体文件下载到本地imgs/和videos/目录
"从不下载" — 保留原始远程URL在Markdown中

问题2 — 标题："输出"，问题："默认输出目录？"

"url-to-markdown（推荐）" — 保存至./url-to-markdown/{domain}/{slug}.md
（用户可选择"其他"来输入自定义路径）

问题3 — 标题："保存"，问题："偏好设置保存位置？"

"用户级（推荐）" — ~/.tuzi-skills/（所有项目通用）
"项目级" — .tuzi-skills/（仅当前项目）

用户回答后，在所选位置创建EXTEND.md，确认"偏好设置已保存至[路径]"，然后继续操作。完整参考：references/config/first-time-setup.md

Supported Keys

支持的配置项

Key	Default	Values	Description
`download_media`	`ask`	`ask` / `1` / `0`	`ask` = prompt each time, `1` = always download, `0` = never
`default_output_dir`	empty	path or empty	Default output directory (empty = `./url-to-markdown/` )

Value priority:

CLI arguments (
```
--download-media
```
,
```
-o
```
)
EXTEND.md
Skill defaults

配置项	默认值	可选值	描述
`download_media`	`ask`	`ask` / `1` / `0`	`ask` = 每次提示， `1` = 始终下载， `0` = 从不下载
`default_output_dir`	空	路径或空	默认输出目录（空 = `./url-to-markdown/` ）

值优先级：

CLI参数（
```
--download-media
```
,
```
-o
```
）
EXTEND.md
Skill默认值

Features

功能特性

Chrome CDP for full JavaScript rendering
Two capture modes: auto or wait-for-user
Clean markdown output with metadata
Handles login-required pages via wait mode
Download images and videos to local directories

基于Chrome CDP实现完整JavaScript渲染
两种抓取模式：自动模式或等待用户信号模式
生成带元数据的简洁Markdown输出
通过等待模式处理需要登录的页面
下载图片和视频到本地目录

Usage

使用方法

bash

undefined

bash

undefined

Auto mode (default) - capture when page loads

自动模式（默认）- 页面加载完成后抓取

npx -y bun ${SKILL_DIR}/scripts/main.ts <url>

Wait mode - wait for user signal before capture

等待模式 - 等待用户信号后再抓取

npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --wait

Save to specific file

保存到指定文件

npx -y bun ${SKILL_DIR}/scripts/main.ts <url> -o output.md

Download images and videos to local directories

下载图片和视频到本地目录

npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --download-media

undefined

npx -y bun ${SKILL_DIR}/scripts/main.ts <url> --download-media

undefined

Options

可选参数

Option	Description
`<url>`	URL to fetch
`-o <path>`	Output file path (default: auto-generated)
`--wait`	Wait for user signal before capturing
`--timeout <ms>`	Page load timeout (default: 30000)
`--download-media`	Download image/video assets to local `imgs/` and `videos/` , and rewrite markdown links to local relative paths

参数	描述
`<url>`	要获取的URL
`-o <path>`	输出文件路径（默认：自动生成）
`--wait`	等待用户信号后再抓取
`--timeout <ms>`	页面加载超时时间（默认：30000）
`--download-media`	将图片/视频资源下载到本地 `imgs/` 和 `videos/` 目录，并将Markdown中的链接重写为本地相对路径

Capture Modes

抓取模式

Mode	Behavior	Use When
Auto (default)	Capture on network idle	Public pages, static content
Wait ( `--wait` )	User signals when ready	Login-required, lazy loading, paywalls

Wait mode workflow:

Run with
```
--wait
```
→ script outputs "Press Enter when ready"
Ask user to confirm page is ready
Send newline to stdin to trigger capture

模式	行为	使用场景
自动模式（默认）	网络空闲时抓取	公开页面、静态内容
等待模式（ `--wait` ）	等待用户确认后抓取	需要登录、懒加载内容、付费墙页面

等待模式工作流程：

使用
```
--wait
```
参数运行脚本 → 脚本输出"准备就绪后按回车键"
询问用户确认页面已准备好
输入换行符触发抓取

Output Format

输出格式

YAML front matter with

url

title

description

author

published

captured_at

fields, followed by converted markdown content.

包含

url

、

title

、

description

、

author

、

published

、

captured_at

字段的YAML前置元数据，其后是转换后的Markdown内容。

Output Directory

输出目录

url-to-markdown/<domain>/<slug>.md

```
<slug>
```
: From page title or URL path (kebab-case, 2-6 words)
Conflict resolution: Append timestamp
```
<slug>-YYYYMMDD-HHMMSS.md
```

When

--download-media

is enabled:

Images are saved to
```
imgs/
```
next to the markdown file
Videos are saved to
```
videos/
```
next to the markdown file
Markdown media links are rewritten to local relative paths

url-to-markdown/<domain>/<slug>.md

```
<slug>
```
：来自页面标题或URL路径（短横线分隔格式，2-6个单词）
冲突解决：追加时间戳
```
<slug>-YYYYMMDD-HHMMSS.md
```

当启用

--download-media

时：

图片保存至Markdown文件旁的
```
imgs/
```
目录
视频保存至Markdown文件旁的
```
videos/
```
目录
Markdown中的媒体链接会被重写为本地相对路径

Media Download Workflow

媒体下载工作流程

Based on

download_media

setting in EXTEND.md:

Setting	Behavior
`1` (always)	Run script with `--download-media` flag
`0` (never)	Run script without `--download-media` flag
`ask` (default)	Follow the ask-each-time flow below

基于EXTEND.md中的

download_media

设置：

设置值	行为
`1` （始终）	使用 `--download-media` 参数运行脚本
`0` （从不）	不使用 `--download-media` 参数运行脚本
`ask` （默认）	遵循以下"每次询问"流程

Ask-Each-Time Flow

每次询问流程

Run script without
```
--download-media
```
→ markdown saved
Check saved markdown for remote media URLs (
```
https://
```
in image/video links)
If no remote media found → done, no prompt needed
If remote media found → use
```
AskUserQuestion
```
:
- header: "Media", question: "Download N images/videos to local files?"
- "Yes" — Download to local directories
- "No" — Keep remote URLs
If user confirms → run script again with
```
--download-media
```
(overwrites markdown with localized links)

不使用
```
--download-media
```
参数运行脚本 → 保存Markdown文件
检查已保存的Markdown文件中是否存在远程媒体URL（图片/视频链接中包含
```
https://
```
）
如果未找到远程媒体 → 操作完成，无需提示
如果找到远程媒体 → 使用
```
AskUserQuestion
```
：
- 标题："媒体文件"，问题："是否下载N个图片/视频到本地文件？"
- "是" — 下载到本地目录
- "否" — 保留远程URL
如果用户确认 → 再次使用
```
--download-media
```
参数运行脚本（覆盖Markdown文件，替换为本地链接）

Environment Variables

环境变量

Variable	Description
`URL_CHROME_PATH`	Custom Chrome executable path
`URL_DATA_DIR`	Custom data directory
`URL_CHROME_PROFILE_DIR`	Custom Chrome profile directory

Troubleshooting: Chrome not found → set

URL_CHROME_PATH

. Timeout → increase

--timeout

. Complex pages → try

--wait

mode.

变量	描述
`URL_CHROME_PATH`	自定义Chrome可执行文件路径
`URL_DATA_DIR`	自定义数据目录
`URL_CHROME_PROFILE_DIR`	自定义Chrome配置文件目录

故障排除：未找到Chrome → 设置

URL_CHROME_PATH

。超时问题 → 增大

--timeout

值。复杂页面 → 尝试

--wait

模式。

Extension Support

扩展支持

Custom configurations via EXTEND.md. See Preferences section for paths and supported options.

通过EXTEND.md进行自定义配置。详见偏好设置部分的路径和支持的配置项。