mdcraft.ai Exporter Spec#

Objective#

Define the Phase 1 contract for Markdown -> PDF.

The exporter is the core of the first release and should feel clearly better than generic browser tools and editor extensions.

HTML export groundwork can share the same render tree, but it is not part of the current public Phase 1 workflow.

Supported input#

• .md
• pasted markdown
• markdown generated by AI tools
• GitHub Flavored Markdown as the baseline syntax

Required syntax support#

• headings
• paragraphs
• emphasis and strong text
• links
• images
• blockquotes
• ordered and unordered lists
• task lists
• tables
• fenced code blocks with syntax highlighting
• inline code
• footnotes
• horizontal rules
• Mermaid diagrams
• math
• callouts or admonition-style blocks

PDF requirements#

Layout#

• stable pagination
• configurable paper sizes: A4 and Letter
• consistent margins
• safe handling for wide tables and code blocks
• optional cover page support
• print-safe page breaks between major sections

Navigation#

• table of contents
• page numbers
• optional running header and footer
• internal links remain clickable

Design quality#

• strong typographic hierarchy
• good defaults for line length, paragraph spacing, and code readability
• image sizing that does not break the layout
• syntax highlighting that survives print use

HTML groundwork (internal / future-facing)#

• semantic markup
• responsive reading layout
• anchor links for headings
• good code rendering
• accessible color contrast
• visual parity with the PDF theme system where practical

Theme system#

The Phase 1 product currently ships with five presets:

1. Technical Docs
   • crisp
   • optimized for code, tables, and product docs
2. Research Paper
   • serif-led
   • formal and citation-friendly
3. Executive Report
   • polished
   • summary and proposal friendly
4. Structured Brief
   • compact
   • clear hierarchy for fast reading
5. Editorial
   • more expressive
   • designed for presentation-quality reading layouts

Theme controls#

• theme preset
• paper size
• margin density
• TOC on or off
• page chrome on or off (header/footer and page numbering)

Non-goals for MVP#

• full WYSIWYG editing
• collaborative commenting
• arbitrary template builders
• Word export
• Google Docs export

Error handling#

• clearly identify unsupported markdown extensions
• warn when Mermaid or math parsing fails
• highlight layout overflow risks before PDF export
• surface missing remote images or blocked assets

Success criteria#

• export result is noticeably more polished than common free tools
• preview and final output are visually close
• no major regressions on tables, code, Mermaid, math, and images across the benchmark suite

Suggested implementation notes#

• normalize markdown through a shared parser before preview and export
• render HTML once and use that same structure as the PDF source
• treat pagination controls as product features, not late-stage styling patches