markdown-to-standalone-html
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.
When & Why to Use This Skill
This Claude skill enables the seamless conversion of Markdown documents into fully self-contained HTML files. By automatically embedding local and remote images as base64 data URIs, it eliminates external dependencies, ensuring your reports, blog posts, and technical documentation remain portable and accessible offline in any web browser. It simplifies the workflow of sharing rich-media documents without the need for external hosting or complex asset management.
Use Cases
- Offline Documentation: Creating technical manuals or project documentation that needs to be shared and viewed without an internet connection or external image hosting.
- Portable Blog Previews: Generating a single-file preview of a blog post with all visual assets included for easy sharing and review via email or messaging apps.
- Self-Contained Reports: Converting data-driven Markdown reports into professional HTML documents where charts and images are baked-in, preventing broken links when archived or moved.
- Educational Handouts: Distributing study guides or lesson notes as a single HTML file that students can open on any device without worrying about missing image files or folder structures.
| 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 conversionruby— Script execution
Both must be on your PATH. The script checks and exits with a clear error if missing.
Workflow
- Prepare your Markdown — Any
.mdfile with images (local paths or public URLs) - Run the conversion script with the Markdown file, title, and output path
- Resolve images — If images can't be found locally, you'll be prompted for a file path or URL
- Get your HTML — A single
.htmlfile with all images embedded, ready to share
Image Resolution
For each image in your Markdown:
- Relative path — Resolved relative to the Markdown file's directory
- Absolute path — Used as-is if it exists
- Public URL (
http://orhttps://) — Downloaded to temp directory, embedded, then cleaned up - 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 CSSbackground-imageURLs) - 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 providedassets/template.html)--out— Path where the final HTML will be written (required)