Markly — Document to Markdown Converter
A converter that turns DOCX, TXT, JSON or messy Markdown into clean, normalized Markdown, then validates the result and flags exactly what still needs a fix.
Context
Turning a Word doc or a pasted block of inconsistent Markdown into something clean enough to commit to a repo or paste into a CMS usually means manual cleanup — fixing spacing, list markers and heading levels by hand. Markly set out to do that cleanup automatically, entirely in the browser, and to be honest about what it couldn't fix on its own.
The Challenge
The product needed to auto-detect and normalize several very different input formats — DOCX, TXT, JSON, and already-written Markdown — into one consistent output, while clearly separating what got fixed automatically from what still needed a human decision.
Research
Collected inconsistently formatted Markdown from several real sources — exported docs, scraped content, hand-written notes — and used the recurring problems (double spacing, inconsistent list markers, missing blank lines) to define what 'clean' needed to mean.
Insights
The key findings that shaped the direction.
Format detection has to be automatic, not a dropdown
Making someone specify whether their input is DOCX, JSON or Markdown before converting adds a decision nobody wants to make — detecting it from the content itself removes a step entirely.
Cleaning and validating are two different jobs
Auto-fixing spacing and list markers is safe to do silently; flagging a broken link or an ambiguous heading level needs a human decision — conflating the two would make either the fixes untrustworthy or the flags noisy.
A validation list beats a single pass/fail
Splitting results into errors, warnings and suggestions gives someone a prioritized list to work through, instead of a single red flag that doesn't say what to do next.
Design Strategy
How decisions were made.
Auto-detect format from content, not a picker
Built detection around the input's own shape — a leading { or [ for JSON, a # for Markdown — so converting starts the moment something is pasted in.
Separate silent cleanup from flagged issues
Let Format Mode silently normalize headings, lists and spacing on conversion, while routing anything genuinely ambiguous into the Validation panel instead of guessing.
Categorize validation by what it means for the user
Split validation results into Errors, Warnings and Suggestions with a Fix All action, so a long list of issues still resolves down to a clear next step.
Keep every document entirely client-side
Ran conversion and validation entirely in the browser with no upload step, since the documents people convert are often internal drafts nobody wants leaving their machine.
Build solo, with AI as the engineering partner
Designed and built end-to-end using Claude Code as a development partner — from the format-detection logic to the validation engine — without a dedicated engineering team, while keeping every UX decision in my hands.
Solution
A client-side document-to-Markdown converter that auto-detects DOCX, TXT, JSON or Markdown input, normalizes formatting on conversion, and validates the result across errors, warnings and suggestions.
A look at the work.
The live product at getmarkly.vercel.app.
Format Mode in action — headings, lists and spacing normalized on conversion.
The Validation panel — errors, warnings and suggestions, with Fix All and Undo.
Design System Thinking
This project wasn't designed as a one-off — here's how it connects back to the system.
Components
A shared dual-pane editor component (input, live output) reused identically regardless of which source format was detected.
Tokens
A consistent severity colour scale — error, warning, suggestion — applied across the validation panel and inline issue markers.
Patterns
A detect-then-clean-then-validate pattern applied to every input, so the interaction model stays the same whether the source was DOCX, JSON or Markdown.
Governance
100% client-side processing with no upload step, so documents never leave the browser, by architecture rather than policy.
Impact
Markly shipped as a free, account-less alternative to manually cleaning up document exports, giving anyone converting content to Markdown a validation pass most tools skip entirely.
Reflection
The temptation was to let Format Mode silently fix everything. Drawing a hard line between what's safe to auto-fix and what needs a flagged decision took more iteration than the conversion logic itself, but it's the reason the tool feels trustworthy instead of just convenient.