AgentSkillsCN

markdown-to-standalone-html

将 Markdown 文档（*.md 文件）转换为自带图片的自足 HTML 文件。适用于需要从 Markdown 生成便携、离线友好的单一 HTML 文件时——非常适合博客文章、随笔、报告，或任何无需外部依赖即可运行的内容。

SKILL.md
--- frontmatter
name: markdown-to-standalone-html
description: Convert Markdown documents (*.md files) to self-contained HTML files with embedded images. Use when you need a portable, offline-friendly single HTML file from Markdown—ideal for blog posts, essays, reports, or any content that should work without external dependencies.

Markdown → Standalone HTML (Embedded Images)

Overview

Convert any Markdown file into a single self-contained HTML document with all images embedded as base64 data URIs. No external hosting required—the output is a single .html file that works offline.

Requirements

  • •pandoc — Markdown → HTML conversion
  • •ruby — Script execution

Both must be on your PATH. The script checks and exits with a clear error if missing.

Workflow

  1. •Prepare your Markdown — Any .md file with images (local paths or public URLs)
  2. •Run the conversion script with the Markdown file, title, and output path
  3. •Resolve images — If images can't be found locally, you'll be prompted for a file path or URL
  4. •Get your HTML — A single .html file with all images embedded, ready to share

Image Resolution

For each image in your Markdown:

  1. •Relative path — Resolved relative to the Markdown file's directory
  2. •Absolute path — Used as-is if it exists
  3. •Public URL (http:// or https://) — Downloaded to temp directory, embedded, then cleaned up
  4. •Unresolved — You're prompted to provide a local file path or URL

All images in the final HTML are base64-encoded and embedded directly—no external dependencies.

Limitations

  • •Only rewrites <img src=""> tags (not CSS background-image URLs)
  • •Does not guess missing images; prompts interactively instead
  • •Untrusted SVG can contain scripts—review embedded SVG carefully

Script Reference

Script: scripts/markdown_to_standalone_html.rb

Usage:

bash
ruby .github/skills/markdown-to-standalone-html/scripts/markdown_to_standalone_html.rb \
  /path/to/post.md \
  --title "Your Post Title" \
  --template .github/skills/markdown-to-standalone-html/assets/template.html \
  --out /path/to/output.html

Arguments:

  • •markdown — Path to your Markdown file (required)
  • •--title — Title for the HTML document (required; displayed in browser tab and header)
  • •--template — Path to the HTML template (required; use the provided assets/template.html)
  • •--out — Path where the final HTML will be written (required)