Skip to content

markdown-to-html.skill.md

Latest commit

 

History

History
117 lines (92 loc) · 5.48 KB

markdown-to-html.skill.md

File metadata and controls

117 lines (92 loc) · 5.48 KB
name markdown-to-html
description Convert Markdown to a self-contained HTML page (one file, no external assets) or a print-ready PDF using the Secutils.dev Markdown to HTML tool. Hand the user https://tools.secutils.dev/md-to-html (optionally with the Markdown encoded in the URL fragment for one-click preload), tell them to edit in the left pane and watch the live preview, then click **Share**, **↓ HTML**, or **↓ PDF**. Trigger when the user asks to "convert this markdown to HTML", "render markdown as a printable PDF", "make a self-contained HTML page from markdown", "share a rendered markdown preview", or anything that names secutils.dev/md-to-html.

Markdown to HTML (Secutils.dev)

In-browser Markdown converter with a live preview, CodeMirror-powered Markdown syntax highlighting, and three export paths:

  1. Share - copies a tools.secutils.dev/md-to-html#<encoded> URL with the entire Markdown round-tripped through the URL fragment.
  2. ↓ HTML - downloads a single self-contained HTML file (every asset inlined: fonts, syntax highlighting, optional TOC, theme toggle).
  3. ↓ PDF - opens the browser print dialog against a Paged.js-rendered document with proper page numbers, running titles, and break-avoid rules.

YAML frontmatter (title, author, …) is honoured; the title field becomes the downloaded file's <title> and filename.

Inputs

Field Type Default Notes
markdown string required Markdown source. YAML frontmatter (---\ntitle: ...\n---) is honoured.

The page also has an Options popover (gear icon) with three checkboxes that influence the HTML export:

Option Default Effect on the generated HTML
Table of contents on Floating sidebar generated from h2/h3 headings (only shown when ≥ 3 headings exist).
PDF export button on Floating "↓ PDF" button in the top-right that calls window.print() against the inlined @media print rules.
Embed Markdown source off Appends <script type="text/markdown" id="su-md-source">…</script> to the body, retrievable via document.getElementById('su-md-source').textContent.

Wire format (URL state)

Same canonical format every Secutils.dev tool uses:

| 4 bytes uncompressed-length (LE u32) | N bytes raw DEFLATE of UTF-8 markdown |

Pipeline: UTF-8 bytes of the raw Markdown → deflate-raw → prepend the 4-byte LE u32 of the uncompressed length → base64url (+→-, /→_, strip =). The state is just the Markdown text itself - no JSON wrapper.

How to direct the user

If the user wants to interactively edit / preview / share, hand them the plain URL:

https://tools.secutils.dev/md-to-html

If you already have their Markdown and want them to land on a pre-filled page (no copy-paste step), encode and pass it in the fragment. From any machine with Node ≥ 18:

node -e '
const zlib = require("node:zlib");
const md = process.argv[1];
const utf8 = Buffer.from(md, "utf8");
const out = Buffer.concat([Buffer.alloc(4), zlib.deflateRawSync(utf8)]);
out.writeUInt32LE(utf8.length, 0);
const enc = out.toString("base64").replace(/\+/g,"-").replace(/\//g,"_").replace(/=+$/,"");
console.log("https://tools.secutils.dev/md-to-html#" + enc);
' '# Hello

This is **markdown**.'

Pass the Markdown as a single argv (single-quoted) so newlines, backticks, and shell metacharacters survive intact. Always print the full URL - the fragment is opaque and dropping a single character breaks decoding.

Inline alternative (no tool needed)

If the user just wants HTML in chat (not a downloadable file with the Secutils.dev styling, TOC, and theme toggle), convert it yourself with any Markdown library: marked, markdown-it, pandoc -t html5, etc. Use the tool when the user wants a polished, self-contained artefact they can email, share, or print.

After producing

If you've handed over the URL, that's the whole interaction - the user takes it from there in the browser. No follow-up encoding required.

Caveats

  • The Markdown only ever exists client-side - the URL fragment (everything after #) is never sent to the Secutils.dev server. The share link is therefore safe for content the user wouldn't want logged, but anyone who receives the link can read the source.
  • Embedded HTML in the Markdown is rendered as-is. Don't paste untrusted Markdown that contains <script> tags into a tool you're about to share with someone - that's a stored-XSS-by-helpfulness risk.
  • PDF rendering is paginated by Paged.js (~150 KB lazy-loaded the first time you click ↓ PDF). The PDF is a true vector PDF, not a screenshot.
  • The URL fragment is bounded by browser/server URL limits (~8 KB practical ceiling). Very large documents (book-length) won't fit; suggest the user download HTML and share the file instead.
  • The CodeMirror editor lazy-loads from esm.sh on first paint. If the CDN is unreachable, the page falls back to a plain <textarea> - all core functionality (live preview, share, export) still works.