Markdown.new
Use this skill to convert public URLs into LLM-ready Markdown via markdown.new.
Path Resolution (Critical)
- - Resolve relative paths like
scripts/... and references/... from the skill directory, not workspace root. - If current directory is unknown, use an absolute script path.
CODEBLOCK0
CODEBLOCK1
Avoid this pattern from an arbitrary workspace root:
CODEBLOCK2
Workflow
- 1. Validate the input URL is public
http or https. - Run
scripts/markdown_new_fetch.py with --method auto first. - Re-run with
--method browser if output misses JS-rendered content. - Enable
--retain-images only when image links are required. - Capture response metadata (
x-markdown-tokens, x-rate-limit-remaining, and JSON metadata when present) for downstream planning.
Quick Start
Commands below assume current directory is the skill root (~/.codex/skills/markdown-new).
CODEBLOCK3
CODEBLOCK4
CODEBLOCK5
Method Selection
- -
auto: default. Let markdown.new use its fastest successful pipeline. - INLINECODE12 : force Workers AI HTML-to-Markdown conversion.
- INLINECODE13 : force headless browser rendering for JS-heavy pages.
Use auto first, then retry with browser only when needed.
Delivery Mode
- - Use
--deliver-md to force file output in .md format. - In delivery mode, content is wrapped as:
-
<url>
-
...markdown...
-
</url>
- - If
--output is omitted, the script auto-generates a filename from the URL.
API Modes
-
https://markdown.new/https://example.com?method=browser&retain_images=true
-
POST https://markdown.new/
- JSON body: INLINECODE24
Prefer POST mode for automation and explicit parameters.
Limits And Safety
- - Treat
429 as rate limiting (documented limit: 500 requests/day/IP). - Convert only publicly accessible pages.
- Respect
robots.txt, terms of service, and copyright constraints. - Do not treat markdown.new output as guaranteed complete for every page; verify critical extractions.
References
Markdown.new
使用此技能通过 markdown.new 将公开 URL 转换为适合 LLM 处理的 Markdown 格式。
路径解析（关键）
- - 相对路径（如 scripts/... 和 references/...）应从技能目录解析，而非工作区根目录。
- 若当前目录未知，请使用绝对脚本路径。
bash
python3 ~/.codex/skills/markdown-new/scripts/markdownnewfetch.py https://example.com
bash
cd ~/.codex/skills/markdown-new
python3 scripts/markdownnewfetch.py https://example.com
避免从任意工作区根目录使用以下模式：
bash
python3 scripts/markdownnewfetch.py https://example.com
工作流程
- 1. 验证输入 URL 为公开的 http 或 https 地址。
- 首先使用 --method auto 运行 scripts/markdownnewfetch.py。
- 若输出缺少 JS 渲染内容，则使用 --method browser 重新运行。
- 仅在需要图片链接时启用 --retain-images。
- 捕获响应元数据（x-markdown-tokens、x-rate-limit-remaining 及 JSON 元数据，如有）供下游规划使用。
快速开始
以下命令假设当前目录为技能根目录（~/.codex/skills/markdown-new）。
bash
python3 scripts/markdownnewfetch.py https://example.com > page.md
bash
python3 scripts/markdownnewfetch.py https://example.com --method browser --retain-images --output page.md
bash
python3 scripts/markdownnewfetch.py https://example.com --deliver-md
方法选择
- - auto：默认值。让 markdown.new 使用其最快的成功管道。
- ai：强制使用 Workers AI 进行 HTML 到 Markdown 的转换。
- browser：强制使用无头浏览器渲染 JS 密集型页面。
首先使用 auto，仅在需要时重试 browser。
交付模式
- - 使用 --deliver-md 强制以 .md 格式输出文件。
- 在交付模式下，内容包装为：
-
- ...markdown...
-
- - 若省略 --output，脚本会根据 URL 自动生成文件名。
API 模式
- https://markdown.new/https://example.com?method=browser&retain_images=true
- POST https://markdown.new/
- JSON 主体：{url:https://example.com,method:auto,retain_images:false}
自动化场景推荐使用 POST 模式及显式参数。
限制与安全
- - 将 429 视为速率限制（文档限制：500 次请求/天/IP）。
- 仅转换可公开访问的页面。
- 遵守 robots.txt、服务条款和版权限制。
- 不要认为 markdown.new 的输出对每个页面都保证完整；关键提取内容需验证。
参考资料
- - references/markdown-new-api.md
