Convert Markdown to HTMX
Deterministic Markdown → single-file HTML conversion with brand styling.
Setup
- Set
artifact_type: html - Set
content_type: direct:html - Source MD file must exist; brand TOML must be registered under
assets/library/brands/
User Input
The user will provide: $ARGUMENTS
Parse for:
--source <path-to-md>(required)--brand <brand-name>(required) — must resolve underassets/library/brands/<name>.toml--output <path-to-html>(required)--document-type article|brief|spec|moodboard|none(optional; defaultarticle; frontmatter overrides)
Procedure
Dispatch to the orchestration script:
node scripts/convert-md-to-htmx.mjs \
--source "${SOURCE}" \
--brand "${BRAND}" \
--output "${OUTPUT}" \
${DOC_TYPE:+--document-type "${DOC_TYPE}"}
The script:
- Reads MD source; extracts YAML/TOML frontmatter via
gray-matter. Frontmatter keys (title,document-type) override CLI flags. - Renders MD → HTML via
markdown-itconfigured for:- GFM tables, task lists, strikethrough
- Auto-linked bare URLs
- Heading anchors via
markdown-it-anchor - Smart typography (curly quotes, em-dashes)
- Wraps the body in semantic HTML per
--document-type:article→<article>with<header>,<main>,<footer>brief/spec→ similar with type labelnone→ bare HTML
- Injects brand CSS via
template-forge render --template vite-shell-css --brand <brand>into an inline<style>block. No external CSS dependency. - Writes a single self-contained
.htmlfile.
Default Constraints
- Output is a single .html file — no external CSS or JS
html: falsein markdown-it — embedded HTML in source MD is escaped (sanitization)- Heading anchors are added for h1-h4 with
header-anchorclass - Brand tokens (
var(--color-bg),var(--color-ink), etc.) are applied via:root - No syntax highlighting — code blocks keep
<code class="language-X">for post-build tooling (Prism, Shiki)
Frontmatter example
---
title: My Article Title
document-type: brief
---
Body content here…
Composition with Other Skills
Markdown source → convert-md-to-htmx → branded HTML
↓
(optional) rebrand-artifact for brand swap
Output Contract
artifact_type: html
content_type: direct:html
outputs:
- path: <output>.html
description: Single self-contained branded HTML document
constraints_satisfied:
- markdown_parsed_via_markdown-it_gfm
- frontmatter_extracted_via_gray-matter
- brand_css_injected_inline
- single_file_no_external_dependencies
References
scripts/convert-md-to-htmx.mjs— orchestration scripttools/template-forge-rs/templates/vite-shell-css.html— brand CSS templateopenspec/changes/phase-3b-aux-conversions/— design rationale