mdcraft.ai — Foundation Document#

Domain: mdcraft.ai Vision: The world's best Markdown document studio — design-first, benchmark-driven, and built for the era of agentic AI. Last Updated: March 16, 2026 Status: Phase 1 core product is implemented; hardening, launch plumbing, and go-live preparation are in progress Execution Style: Keep launch and implementation communication short, direct, and action-focused; avoid long explanations unless explicitly requested.

1. What Is mdcraft.ai?#

mdcraft.ai is a web-based, design-first Markdown document studio focused on turning Markdown into beautifully designed outputs and recovering editable Markdown from text-first PDFs. Unlike existing tools that treat conversion as a side feature or produce ugly/broken output, mdcraft.ai treats design quality as the core product.

The goal is still to be the Canva of Markdown conversion — where every export looks professional, polished, and Notion-quality by default, without requiring command-line tools or manual cleanup.

1.1 Current Product Shape#

The current repository already reflects a real Phase 1 product shape:

• A premium landing page with quick-start intake and handoff into the studio
• A /workbench studio for both Markdown -> PDF and PDF -> Markdown beta
• A review-first workflow with live preview, theme controls, warnings, and quick fixes
• A simplified account-backed layer for Google-first sign-in, email/password fallback, password reset, profile defaults, entitlements, and usage tracking
• Benchmark and pagination test infrastructure that acts as an execution-quality bar

1.2 Execution Snapshot#

Done now:

• Premium landing page with homepage quick-start handoff into the studio
• Unified /workbench flow for both Markdown -> PDF and PDF -> Markdown beta
• Shared Markdown preview/export pipeline with GFM, syntax highlighting, Mermaid, KaTeX, anchors, and admonition handling
• Shared DOM pagination engine with preview/export parity, pagination fixtures, and acceptance checks
• Benchmark infrastructure and benchmark-based quality gates in the repository
• Account/auth foundation with PostgreSQL, Prisma, NextAuth, route guards, profile defaults, entitlements, and usage metering
• Simplified /auth UX with Google-first login, email/password fallback, password reset, and lower-friction email-first flow
• Server-backed access enforcement for export/conversion routes
• Billing/provider seams and future API readiness, without live Stripe yet

Next steps:

• Harden export quality for extreme pagination and rendering edge cases
• Improve PDF -> Markdown recovery quality for harder real-world documents
• Add OCR support for scanned/image PDFs
• Finalize access policy, pricing limits, billing truth, and launch analytics
• Formalize privacy posture and decide when exports/conversions should move to queues/workers

2. Why This Exists — Market Context#

2.1 Markdown Is Exploding#

Markdown has evolved far beyond README files. It is now the primary instruction and communication layer for AI agents, developer workflows, and enterprise documentation:

• AI coding agents (GitHub Copilot, Claude Code, Cursor) use .md files as their instruction layer (e.g., CLAUDE.md, copilot-instructions.md, SKILL.md).
• Cloudflare launched "Markdown for Agents" in 2025, converting HTML to Markdown at the network edge for AI crawlers — treating Markdown as a first-class web format.
• 84% of developers use or plan to use AI tools (2025), and 41% of all code is AI-generated. These workflows constantly produce and consume Markdown.
• Enterprises are converting legacy DOCX archives to Markdown to feed AI pipelines (RAG, knowledge bases, LLM training).

2.2 The Problem We Solve#

Existing Markdown conversion tools are fragmented, ugly, or require technical expertise:

• Free online converters (markdowntopdf.com, md2pdf) produce bare-bones, poorly styled output with no customization.
• Developer tools (Pandoc + LaTeX) are powerful but require command-line skills and manual intervention for edge cases.
• Desktop editors (Typora, Mark Text) have export features but aren't web-based conversion platforms.
• Platforms (Notion, HackMD) treat conversion as a secondary feature, not the core product.

Common pain points across all existing solutions:

• Broken internal PDF links and table of contents
• Poor or missing syntax highlighting for code blocks
• Code that overflows the page without proper line wrapping
• Ugly default styling — no "design quality" out of the box
• No support for Mermaid diagrams, LaTeX math, or advanced Markdown extensions
• Requires technical knowledge to get decent results

2.3 Who Needs This#

3. Product Strategy — Phased Roadmap#

Phase 1: Launch (MVP)#

Goal: Nail the core conversion with best-in-class design quality.

Scope:

• Markdown → Beautifully styled PDF
• PDF → Review-first Markdown beta for text-first PDFs

Current implementation snapshot:

• One studio handles Markdown and PDF inputs from a single upload surface
• Five built-in presets currently ship in the product shape:
  • Technical Docs
  • Research Paper
  • Executive Report
  • Structured Brief
  • Editorial
• Current studio controls include theme preset, paper size, spacing density, table of contents toggle, header/footer toggle, live preview, OCR beta toggle, risk scan, and quick fixes
• Shared DOM pagination now drives both preview and PDF export, backed by fixtures and acceptance scripts
• Account-backed profile defaults, entitlements, usage metering, and a simplified email-first auth flow are already modeled in the app
• HTML export groundwork exists in the codebase, but HTML workflows are not yet part of the public Phase 1 surface

Phase 1 quality bar:

• Multiple professional presets for common Markdown document types
• Proper syntax highlighting for all major programming languages
• Working internal links and auto-generated table of contents
• Correct table rendering with clean styling
• Proper code block handling (line wrapping, overflow prevention)
• Mermaid diagram rendering
• LaTeX/KaTeX math expression support
• GitHub Flavored Markdown (GFM) full support
• Drag-and-drop file upload + paste-from-clipboard
• Live preview before export
• Review-first PDF → Markdown with warnings, confidence signals, and quick fixes
• Mobile-responsive web interface around the core studio

Design principles for Phase 1:

• Every PDF output should look like it came from Notion or a professional design tool — not a raw HTML print
• Zero-config beauty: the default output must be stunning without any user customization
• Power users should be able to tweak the workflow in stages: presets, paper size, spacing, TOC/header-footer first; deeper branding controls can come later

Remaining Phase 1 execution priorities:

• Harden pagination/rendering for tall code blocks, long tables, large Mermaid diagrams, and harder nested content
• Improve PDF -> Markdown recovery for tables, lists, code blocks, and lower-confidence files
• Add OCR for scanned PDFs
• Finalize access policy, limits, billing, analytics, and privacy decisions needed for launch

Phase 2: Growth#

Goal: Expand format support and unlock developer/team use cases.

Scope — additional conversions:

• Markdown ↔ HTML (move from groundwork to user-facing workflow)
• Markdown ↔ DOCX (huge enterprise demand)
• Markdown ↔ EPUB
• HTML → Markdown (web page to clean Markdown)

New capabilities:

• API access for programmatic conversion (REST API)
• Batch conversion (upload multiple files, get a ZIP)
• Custom CSS themes / template editor
• Team workspaces with shared templates
• Webhook integrations (GitHub, GitLab — auto-convert on push)
• AI-powered features: auto-formatting, structure detection, content cleanup

Phase 3: Platform#

Goal: Become the universal Markdown conversion hub.

Scope — additional conversions:

• Markdown → PPTX (slide generation from Markdown)
• Markdown → Static HTML websites
• CSV/JSON → Markdown tables
• Markdown ↔ LaTeX
• Markdown ↔ RST (reStructuredText)
• Confluence/Wiki → Markdown

Platform features:

• Plugin/extension system for custom converters
• White-label API for other SaaS products to embed
• AI writing assistant (edit, improve, restructure Markdown before export)
• Template marketplace (community-created templates)
• Desktop app / CLI tool companion

4. Competitive Positioning#

4.1 How We Differentiate#

4.2 Key Competitors to Watch#

• Pandoc — The "Swiss army knife" of document conversion. Powerful but CLI-only and steep learning curve.
• Typora ($15 one-time) — Beautiful WYSIWYG Markdown editor with export. Desktop-only, not a web platform.
• Diwadi ($29 one-time) — Local AI Markdown editor with PDF export. Desktop-only, newer entrant.
• markdowntopdf.com / md2pdf — Free web converters. Minimal features, poor design quality.
• LightPDF — General PDF tool that added Markdown conversion. Not Markdown-focused.
• HackMD — Collaborative Markdown editor with export. Conversion is a side feature.

4.3 Our Moat#

1. Design obsession — Templates and output quality that no free tool matches
2. Markdown-native intelligence — Deep understanding of Markdown extensions, edge cases, and rendering
3. AI-era workflow fit — mdcraft is already useful for AI-generated Markdown and agent outputs, with room for AI-assisted cleanup later
4. Developer-friendly API — Enables programmatic workflows and integrations
5. Brand positioning — "mdcraft" = craft, quality, care. The .ai domain signals intelligence

5. Business Model#

Pricing Strategy (Current product model + launch direction)#

Free Tier:

• Limited daily studio runs
• Core studio access with account-backed defaults
• Best for trying export quality and scoped reverse-conversion beta

Pro Tier ($8/month):

• Unlimited access to the design-first Markdown studio
• Saved defaults across sessions
• Markdown -> PDF plus PDF -> Markdown beta
• Billed monthly; cancel anytime

Enterprise (contact-led later):

• Not part of the self-serve launch offer
• Reserved for procurement, API access, and larger rollout support once those needs are real

Important current reality:

• The public launch pricing direction is Free + one monthly Pro plan at $8/month
• Enterprise remains contact-led and off the main launch pricing surface
• The codebase still models Free, Pro, and Enterprise
• Stripe checkout, billing portal, and webhook flows now exist in code, but each environment still needs real Stripe configuration
• Watermarks, batch conversion, custom CSS/branding, and API monetization remain future capabilities rather than launched features

Revenue Growth Levers#

• Template marketplace (take a cut of community template sales)
• White-label partnerships (other SaaS products embed mdcraft conversion)
• Enterprise contracts for bulk DOCX → Markdown migration

6. Technical Direction (High-Level)#

Architecture Principles#

• Web-first: The primary experience is the browser. No installs required.
• Fast: Conversion should feel instant for typical files (<100 pages).
• Secure: Prefer ephemeral processing and explicit privacy boundaries. Browser-side staging and optional third-party OCR must be clearly documented.
• Extensible: Template system and API should be designed for expansion from day one.
• Shared rendering: Preview and export should come from the same rendering pipeline.
• Review-first reverse conversion: PDF recovery quality should be surfaced honestly through warnings and quick fixes, not hidden behind one-click marketing.

Chosen Phase 1 Stack#

• Frontend and app shell: Next.js App Router + React + Tailwind CSS
• Markdown rendering: unified / remark / rehype pipeline with GFM, math, syntax highlighting, Mermaid, and admonition handling
• PDF generation: Node runtime + Playwright / Chromium HTML-to-PDF with custom pagination
• Theme system: preset-driven HTML/CSS themes applied to a shared export document
• PDF → Markdown: deterministic pdf2json extraction with structure heuristics, warnings, quick fixes, and optional OCR-provider fallback
• Data/auth/platform: Prisma + PostgreSQL + NextAuth
• Product control plane: account-backed profile defaults, entitlements, route guards, and usage metering
• Storage model: request-time processing by default; short-lived browser storage may be used for homepage-to-workbench handoff; mdcraft is not currently a persistent workspace/document-storage product

Current Technical Reality#

• Preview, docs rendering, HTML export groundwork, and PDF export all depend on the same Markdown pipeline
• PDF → Markdown is deterministic today, not AI-assisted
• The account/auth layer is implemented today, including Google-ready login, email/password fallback, password reset, profile defaults, entitlements, and usage enforcement
• The public auth experience has already been simplified into a lower-friction email-first flow
• Billing provider abstraction exists, but checkout/portal/webhooks are still placeholders until Stripe is connected

7. Brand & Domain#

• Domain: mdcraft.ai
• Name meaning: "md" = Markdown file extension. "craft" = quality, care, artisanship. ".ai" = AI-powered intelligence.
• Tagline ideas:
  • "Beautifully crafted Markdown exports"
  • "Your Markdown, perfected"
  • "The converter your Markdown deserves"
• Brand personality: Professional but approachable. Design-forward. Developer-friendly without being developer-exclusive.

8. Success Metrics#

Phase 1 KPIs#

• Monthly active users (target: 5,000+ within 3 months of launch)
• Conversion volume (files processed per day)
• Benchmark gate pass rate and pagination acceptance reliability
• User satisfaction with output quality (NPS, design rating)
• Free → Pro conversion rate (target: 3-5%)

Phase 2 KPIs#

• API adoption (number of developer accounts, API calls/month)
• Enterprise plan adoption
• Format coverage (number of supported conversion paths)
• Retention rate (monthly active returning users)

Long-term North Star#

• Become the default answer to "how do I convert my Markdown file?" across the internet

Current execution note#

• Benchmark-based quality gates already exist in the repository
• Product analytics and experimentation instrumentation are still an open rollout task

9. Stage-by-Stage Execution Plan#

Stage 0: Completed Foundation Work (Done)#

• Build the premium landing page and homepage quick-start handoff
• Implement the unified workbench for Markdown -> PDF and PDF -> Markdown beta
• Establish the shared Markdown rendering pipeline for preview and export
• Implement shared DOM pagination with preview/export parity
• Add pagination fixtures, acceptance scripts, and benchmark infrastructure
• Add the account/data/auth foundation with profile defaults, entitlements, and usage metering
• Simplify /auth into a cleaner Google-first, email-first, password-reset-enabled flow
• Add server-backed route enforcement for export/conversion usage
• Add billing/provider seams and API-ready schema fields without turning on live billing

Stage 1: Phase 1 Quality Hardening (Next)#

• Harden pagination for very tall code blocks, long tables, large Mermaid diagrams, and complex nested content
• Improve preview/export visual parity and overall document-viewer polish
• Expand fixture and benchmark coverage for forward export regressions
• Improve PDF -> Markdown recovery for tables, lists, code blocks, and confidence messaging

Stage 2: Phase 1 Capability Completion (Next)#

• Add OCR support for scanned/image PDFs
• Finalize launch-time studio access policy (public, softGate, or hardGate)
• Decide whether Free limits remain daily or shift to monthly before launch messaging hardens
• Decide when HTML export and HTML → Markdown become public workflows
• Formalize privacy/security posture for browser-staged files and optional OCR-provider processing

Stage 3: Launch Plumbing (Next)#

• Connect Stripe checkout, customer portal, and webhooks
• Make billing the source of truth for entitlements
• Finalize analytics and experimentation instrumentation for activation, export success, and upgrade funnels
• Validate pricing and launch messaging before broad rollout

Stage 4: Go-Live Readiness (Next)#

• Decide when export/conversion should move from synchronous request handling to queues/workers
• Tighten privacy/compliance posture (retention, provider disclosure, EU/GDPR readiness)
• Prepare SEO/tutorial content and launch-channel support material

Stage 5: Phase 2 Growth (Next after Phase 1 launch)#

• Move Markdown/HTML workflows from groundwork into public product surface
• Add API access
• Add batch conversion
• Add custom CSS themes / template editor
• Add webhook and automation readiness
• Revisit team/shared-template workflows only after Phase 1 quality is genuinely strong

Stage 6: Phase 3 Platform (Later)#

• Expand into additional formats such as DOCX, EPUB, PPTX, static HTML, and wiki ecosystems
• Add plugin/extension support
• Add white-label/API platform capabilities
• Explore AI-assisted writing, cleanup, and restructuring on top of the core conversion product

10. Open Questions & Decisions Needed#

• Finalize the launch-time studio access policy (public, softGate, or hardGate)
• Connect Stripe checkout, customer portal, and webhooks, then define billing as the source of truth
• Decide whether Free-plan limits remain daily or shift to monthly before launch messaging hardens
• Decide when HTML export and HTML → Markdown become user-facing workflows
• Formalize privacy/security posture for browser-staged files and optional OCR-provider processing
• Decide when export/conversion should move from synchronous request handling to queues/workers
• Finalize analytics and experimentation instrumentation for activation, export success, and upgrade funnels
• Pricing validation: survey potential users on willingness to pay
• Privacy/compliance posture: EU hosting? GDPR compliance from day one?
• SEO strategy: content marketing around Markdown tutorials and conversion guides
• Launch channel: Product Hunt, Hacker News, dev communities, or organic SEO?

This document is the source of truth for the mdcraft.ai project. All development, design, and strategic decisions should reference and align with this foundation. Update this document as decisions are made and the product evolves.