html-markdown-hybrid（HTML Markdown hybrid 控制）

HTML Markdown Hybrid

Overview

This skill combines the best parts of two separate tools:

• scripts/pretty_markdown_to_html.py for better-looking Markdown to HTML output
• scripts/html_to_markdown.mjs for stronger HTML to Markdown conversion, URL fetching, cleanup profiles, metadata, and reports
• scripts/markdown_to_html.mjs as an optional Node-based Markdown to HTML fallback when batch directory conversion or theme switching is more important than final polish

Decision rule

Use this skill when the task is any of the following:

• turn Markdown into a presentable standalone HTML page
• convert a web page, raw HTML, or HTML file into clean Markdown
• batch-convert many Markdown or HTML files
• keep article-style readability cleanup or metadata during conversion
• compare conversion quality between a pretty renderer and a more configurable pipeline

Recommended default path

Markdown → HTML

Use the Python renderer first when visual output quality matters most.

python scripts/pretty_markdown_to_html.py input.md -o output.html --theme light --title "Document"

Use this for:

• AI日报转网页
• 文档展示页
• 报告、newsletter、分享页
• 任何最终要给人直接阅读的 HTML 页面

Why this is the default:

• it produces cleaner default styling
• it embeds CSS inline
• it is lighter and simpler to run
• this copy is patched to read and write UTF-8 explicitly on Windows

HTML → Markdown

Use the Node pipeline first for HTML extraction and cleanup.

node scripts/html_to_markdown.mjs \
  --url "https://example.com/article" \
  --out ./article.md \
  --profile article \
  --engine best \
  --meta-frontmatter true \
  --report ./article.report.json

Use this for:

• 网页文章转 Markdown
• HTML 文件清洗后转 Markdown
• 批量转换目录
• URL 列表抓取转 Markdown

Read references/profiles.md when choosing article, docs, forum, or custom.

Optional fallback: Markdown → HTML with Node

Use the Node renderer when you need directory batch conversion or its built-in themes.

node scripts/markdown_to_html.mjs \
  --file ./README.md \
  --out ./README.html \
  --theme github

Use it when:

• converting an entire markdown directory to HTML
• the github or minimal theme is specifically desired
• one workflow should stay entirely inside Node

Do not make this the first choice when the user explicitly cares most about frontend presentation quality.

Quick chooser

• Best-looking Markdown page → pretty_markdown_to_html.py
• Web article to clean Markdown → html_to_markdown.mjs --profile article
• Docs portal to Markdown → html_to_markdown.mjs --profile docs
• Batch Markdown folder to HTML → markdown_to_html.mjs --input-dir ... --output-dir ...
• Need metadata/report/frontmatter → use the Node HTML to Markdown script

Files in this skill

• scripts/pretty_markdown_to_html.py
• scripts/html_to_markdown.mjs
• scripts/markdown_to_html.mjs
• references/profiles.md
• package.json

Setup notes

The Node scripts depend on packages listed in package.json. If dependencies are not installed yet, run:

npm install

from the skill directory before using the Node scripts.

The Python renderer uses only the standard library and needs no extra dependencies.

Practical recommendation

For the exact kind of comparison where the same AI news markdown was rendered two ways, prefer:

• Markdown source → pretty_markdown_to_html.py
• HTML/article source → html_to_markdown.mjs

That gives the stronger visual result in one direction and the stronger cleanup/extraction result in the other.