Why is exporting Markdown to HTML so hard to get right?
Markdown is the ideal writing format — plain text, version-friendly, content-focused. But when you need to share your work, problems appear: send a .md file and the recipient needs a Markdown viewer; convert to PDF and the print-heavy feel makes mobile reading terrible; copy to a rich-text editor and formatting usually breaks.
Exporting to HTML is the natural choice — browsers support it natively, any device can open it. But there’s a wide gap between “can be opened” and “looks good”: bare HTML has no styles, code blocks are black-and-white, dark mode is either completely absent or requires manually maintaining a CSS file.
What makes “beautiful HTML”?
A high-quality Markdown → HTML export should meet these standards:
- Single file — all styles inlined, no external CSS/JS/fonts, can be sent directly or hosted on any static server
- Built-in dark mode — auto-switches with the system via
@media (prefers-color-scheme: dark), no JS required - Themed code blocks — syntax highlight colors that harmonize with the overall palette, not a generic black background
- Refined typography — proper line height, font sizes, font stacks, paragraph spacing; tables, blockquotes, and math formulas all styled
- Controlled content width — doesn’t stretch across the full browser width; maintains a comfortable reading column (typically 65–80 characters)
The Design Token theme system
Mark.build uses Design Tokens as the core architecture for theming. Every visual property — text color, background color, code block background, accent color, border radius, fonts — is managed through tokens rather than scattered hardcoded values.
Tokens are organized in three layers:
- Primitive — color scales (
blue.600,gray.100), font names, font sizes - Semantic —
text-primary,bg-surface,accent, each with both light and dark values defined - Component —
code-block.bg,table.header-bg, automatically derived from Semantic
When you switch themes, every element — headings, paragraphs, code blocks, Mermaid diagrams, KaTeX formulas, tables — pulls from the same token set and updates instantly. The code block highlighting scheme changes with the theme too, rather than being fixed to one palette.
Step-by-step guide to exporting HTML with Mark.build
Step 1: Open the editor
Visit mark.build/editor. The editor is built on CodeMirror 6, with syntax highlighting, keyboard shortcuts (⌘B bold, ⌘I italic, ⌘K link), and scroll-synced preview. All documents are saved locally in the browser — nothing uploaded to a server.
Step 2: Choose a theme
Click the theme selector in the toolbar and pick from the built-in themes:
- Default — clean blue accent, ideal for technical documentation
- Tech Blog — purple accent + dark code blocks, Dracula-inspired
- Academic — serif heading font, great for papers and long-form writing
- Minimal — minimalist gray palette, reduces visual noise
- Magazine — red accent + Playfair Display headings, magazine aesthetic
Use the sun/moon icon in the toolbar to toggle between light and dark mode and preview the result.
Step 3: Export HTML
Click “Export” in the top-right corner and choose “Export HTML”. The exported file is a fully self-contained .html file:
- All CSS is inlined in a
<style>tag, including the minimal styles needed to render KaTeX formulas - Both light and dark CSS variable sets are written into the file, switching automatically via
@media (prefers-color-scheme: dark) - Mermaid diagrams are exported as inline SVGs — no external runtime needed
Other export formats
Beyond HTML, Mark.build also supports:
- PDF — uses the browser’s print dialog, light mode only, great for clean printable documents
- PNG — captures the preview area at 2× pixel density, ideal for social media sharing
- Rich text copy — copies styled HTML to the clipboard for direct pasting into WeChat, Notion, or email clients
Typical use cases for HTML export
- Publishing technical documentation to a personal website or company intranet without a CMS
- Technical reports for clients or colleagues — one file, no software required
- Attaching an HTML file to an email that opens directly in any browser
- Uploading to GitHub Pages or Cloudflare Pages to become an accessible web page in seconds
- Single-page resumes or portfolio pieces — beautiful styling, automatic dark mode
Summary
The end of a Markdown writing workflow shouldn’t be a messy HTML file. A Design Token-driven theme system ensures every exported file has a complete typographic system — not just “readable”.
Mark.build’s goal is to make this as simple as possible: write Markdown, pick a theme, click export. The rest is handled for you.
Try it now: Open the editor →