playbooks

home / skills / michaelvessia / nixos-config / md-to-html

md-to-html skill

/modules/programs/claude-code/skills/md-to-html

This skill converts markdown to self-contained, styled HTML optimized for copying into Google Docs by embedding images and styling tables and code.

npx playbooks add skill michaelvessia/nixos-config --skill md-to-html

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.4 KB
---
name: md-to-html
description: Convert markdown to styled HTML for pasting into Google Docs. Use when the user wants to copy markdown (with tables, images, code blocks) into Google Docs or similar.
allowed-tools: Bash, Read
---

# Markdown to HTML

Converts markdown files to self-contained, styled HTML optimized for copying into Google Docs. Tables get proper borders, code blocks are styled, and images are embedded.

## Usage

Run the script via bunx:

```bash
bunx ~/nixos-config/modules/programs/claude-code/skills/md-to-html/md-to-html.ts "<markdown-file>"
```

## What it does

1. Converts markdown to HTML via pandoc (uses `nix run` if not installed)
2. Applies clean, modern CSS (system fonts, bordered tables, styled code blocks)
3. Embeds all images as base64 (self-contained)
4. Opens the result in the default browser
5. User can then Cmd+A, Cmd+C, paste into Google Docs

## Output

- Creates `/tmp/<filename>.html`
- Opens in browser automatically

## CSS Features

- System fonts (SF Pro, Segoe UI, etc.)
- Tables: auto-width, 1px borders, grey headers
- Code blocks: light grey background, rounded corners
- Blockquotes: left border accent
- Images: max-width 100%
- Reasonable max-width container (900px)

## Notes

- Requires pandoc (script will use `nix run nixpkgs#pandoc` as fallback)
- Images in markdown must be accessible from the markdown file's directory
- Best results when copying from Safari/Chrome to Google Docs

Overview

This skill converts Markdown files into self-contained, styled HTML optimized for copying into Google Docs or similar editors. It produces an HTML file with embedded images, table borders, and readable code block styling so pasted content retains layout and formatting. The result opens in your browser for easy Cmd/Ctrl+A and copy-paste into Google Docs.

How this skill works

The tool runs pandoc (or falls back to a nix-run pandoc) to convert Markdown to HTML, then injects a clean, modern CSS that enforces system fonts, table borders, code block styling, and responsive images. All image references are embedded as base64 so the output is self-contained. It writes the file to /tmp/<filename>.html and opens it in your default browser for immediate copying.

When to use it

  • You need to paste Markdown content into Google Docs and preserve tables, code blocks, and images.
  • You want a single, self-contained HTML file that opens in a browser for easy copy-paste workflows.
  • You have Markdown with local images and want those images embedded for transfer.
  • You prefer a consistent, print-friendly visual style before pasting into a document editor.
  • You need minimal manual cleanup after pasting Markdown into Docs.

Best practices

  • Run the script from the directory containing your Markdown and image files so relative image paths resolve correctly.
  • Use Safari or Chrome when copying from the browser to Google Docs for best fidelity.
  • Ensure pandoc is available or allow the script to use nix run to provide it.
  • Keep images reasonably sized to avoid very large base64 outputs.
  • Preview the file in the browser and use Cmd/Ctrl+A then Cmd/Ctrl+C to copy everything before pasting.

Example use cases

  • Convert a README with tables and screenshots into a Google Docs report without reformatting.
  • Prepare code snippets and explanation for a shared doc while keeping code block styling intact.
  • Convert meeting notes written in Markdown (with local images) into a collaborative Google Doc.
  • Export a Markdown-based tutorial with bordered tables and embedded images for distribution via Docs.

FAQ

Do images need to be online for embedding?

No. Local images referenced from the Markdown file are embedded as base64 so the HTML is self-contained.

What if pandoc is not installed?

The script attempts to use pandoc and will fall back to running pandoc via nix (nix run nixpkgs#pandoc) if pandoc is missing.