Markdown → Standalone HTML (Embedded Images)

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:

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)