HTML Markdown Hybrid

Combine high-quality Markdown to HTML rendering with robust HTML to Markdown extraction in one skill. Use when converting Markdown into nicer-looking standal...

Security Scan

The files, instructions, and requested runtime actions line up with the described Markdown↔HTML conversion purpose; there are no unexpected credentials or opaque installs, though the Node scripts fetch remote URLs and may call external binaries (e.g., pandoc) if chosen — review before running.

Purpose & Capability

The skill name/description match the provided files and README: Python and Node scripts implement Markdown→HTML and HTML→Markdown conversions, batch modes, profiles, and reporting. Declared dependencies and the package.json align with the claimed Node functionality. Nothing in the manifest asks for unrelated credentials or system access.

Instruction Scope

SKILL.md instructs the agent to run the included scripts, explains when to use each, and tells the user to run `npm install` for Node dependencies. The Node script legitimately fetches URLs, reads files/directories, and writes output files (expected for an HTML→Markdown tool). There are no instructions to read unrelated system config, secrets, or to transmit data to unknown external endpoints.

Install Mechanism

There is no packaged install spec; the Node code requires running `npm install` in the skill directory to fetch normal npm packages (package.json and package-lock.json reference standard libraries from the public registry). This is proportional, but running `npm install` will write node_modules to disk and pull third-party packages — standard but worth noting.

Credentials

The skill declares no required environment variables, credentials, or config paths. The operations (file IO, network fetch) are consistent with conversion tasks; nothing requests unrelated secrets or tokens.

Persistence & Privilege

always:false and model invocation are default. The skill does not request persistent or elevated platform privileges. Its files are self-contained and do not attempt to modify other skills or global agent configuration.

Assessment

This skill appears coherent and implements what it claims, but take the usual precautions before running code: 1) Inspect the included scripts (you already have them) and confirm you are comfortable with their behavior. 2) If you run the Node pipeline, run `npm install` in an isolated/sandboxed environment (it will download typical npm packages from the public registry). 3) Be aware the Node HTML→Markdown script will fetch remote URLs and can batch-process URL lists — only process trusted URL lists and avoid feeding sensitive internal URLs. 4) The Node script imports child_process.spawn (likely used to call an external 'pandoc' engine when --engine pandoc is selected) — do not enable that engine unless you trust the system pandoc binary and inputs. 5) Run the Python renderer and Node scripts with non-privileged user rights and review outputs before publishing. If you want lower risk, prefer the Python renderer (no extra deps) or run the Node tools inside a container.

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.