DEV Community: frank

I Tested What a Browser-Based DOCX-to-Markdown Converter Actually Preserves

frank — Sun, 02 Aug 2026 05:59:41 +0000

“Preserves formatting” is one of the least useful promises a document converter can make.

Which formatting?

A Word document can contain semantic heading styles, font sizes, colors, numbered lists, floating objects, page headers, merged table cells, tracked changes, comments, and embedded images. Markdown has no direct representation for many of those things.

So I stopped asking whether DOCX-to-Markdown conversion “works” and tested a narrower question:

Which document structures survive, which become plain text, and which require a deliberate cleanup decision?

I created two controlled .docx files and converted them with MDFold’s browser-based Word to Markdown tool. The first represented a well-structured technical document. The second deliberately used features that are easy to misinterpret or awkward to express in Markdown.

The result was not “everything preserved” or “formatting lost.” It was much more useful:

real Word heading styles became Markdown headings;
bold, italic, links, bullets, and numbered lists survived;
a large bold paragraph stayed bold instead of becoming a heading;
table text survived, but table structure did not;
headers and footers were omitted;
an embedded raster image became a self-contained data URI;
page layout, fonts, and visual positioning were not reproduced.

That is the behavior this article explains and turns into a repeatable workflow.

DOCX and Markdown describe different things

DOCX can describe both document meaning and page presentation. Markdown mostly describes lightweight document structure.

Microsoft’s explanation of WordprocessingML shows that a Word document is composed of structured elements such as paragraphs and runs, with styles and properties attached to them. A paragraph can be a real Heading 1, or it can be an ordinary paragraph that merely looks like a title because someone made it 22-point bold text.

Those two paragraphs may look almost identical in Word. They are not equivalent to a converter.

The conversion pipeline I tested uses Mammoth to interpret DOCX structure as HTML, then converts that HTML into Markdown. Mammoth’s own documentation is unusually honest about the boundary: DOCX and HTML have a large structural mismatch, and conversion works best when the Word document uses styles for their intended meaning.

That gives us the first rule:

Prepare Word for structural conversion, not visual imitation.

If your real goal is to reproduce page margins, floating text boxes, fonts, headers, or exact pagination, Markdown is the wrong destination. Use PDF for a fixed result or keep the document in DOCX for collaborative editing.

The controlled test documents

I used generated files rather than a convenient hand-picked customer document. This made every expected result explicit and kept personal information out of the screenshots.

Test A: semantic structure

The representative file contained:

a real Word Heading 1;
a real Heading 2;
one sentence containing bold and italic runs;
an external hyperlink with descriptive text;
two bullet items;
two numbered steps;
a distinctive final checkpoint sentence.

The expected Markdown was:

# DOCX Conversion Field Test

## Release checklist

The **owner** reviews the _generated Markdown_ before publishing.

[Open the release runbook](https://example.com/runbook)

- Verify the title
- Verify the final paragraph

1. Convert the DOCX
2. Review the Markdown

FINAL CHECKPOINT: names, numbers, and links still match.

Test B: features that need judgment

The difficult file contained:

a visually large, bold title that was still a normal Word paragraph;
underlined text;
a two-column table;
an embedded PNG with alternative text;
a page header and footer;
a distinctive final checkpoint sentence.

This second file was designed to prevent a false sense of success. A converter can return non-empty Markdown while still losing the distinction that matters.

The well-structured document converted cleanly

The representative file preserved every checkpoint we asserted: heading levels, emphasis, link destination, both list types, and the final sentence.

The generated Markdown was not character-for-character identical to my hand-written expectation. The converter used extra spaces after list markers:

-   Verify the title
-   Verify the final paragraph

1.  Convert the DOCX
2.  Review the Markdown

That difference is harmless in common Markdown renderers. It is also a useful reminder not to confuse stylistic normalization with information loss.

The important checks were structural:

Word input	Observed Markdown	Result
Heading 1 style	`# DOCX Conversion Field Test`	Preserved
Heading 2 style	`## Release checklist`	Preserved
Bold run	`owner`	Preserved
Italic run	`_generated Markdown_`	Preserved
External hyperlink	Markdown link with the same destination	Preserved
Bullet list	Hyphen list	Preserved
Numbered list	Ordered Markdown list	Preserved
Final checkpoint	Same sentence in the result	Preserved

This is the kind of Word document that converts well: the author used real structure and kept the layout linear.

A title that only looks like a title stays ordinary text

The difficult document began with VISUAL-ONLY TITLE in a large, bold font. It looked like a heading in Word, but it was not assigned a heading style.

The observed Markdown was:

**VISUAL-ONLY TITLE**

This is correct behavior.

Automatically turning every short bold paragraph into a heading would create false structure in labels, warnings, captions, and emphasized sentences. A converter should prefer the document’s semantic style over a guess based on appearance.

Before conversion, open Word’s Navigation pane. If an intended section title does not appear in the document outline, apply the correct Heading style. Do not merely increase the font size.

Microsoft’s Open XML paragraph-style documentation supports this distinction: paragraph style is an explicit document property, separate from the runs that carry text and visual formatting.

Table text survived, but the table did not

This was the most important limitation in the test.

The DOCX table contained:

Owner	Status
Platform	Ready

The observed output was:

Owner

Status

Platform

Ready

The words survived. The row-and-column relationship did not.

The difficult file produced valid Markdown text, but valid is not the same as structurally complete. The table must be rebuilt and checked against the source.

This matters because a flattened table can silently change meaning. Four values in the correct order may still be unusable when the reader cannot tell which header belongs to which value.

For a small table, rebuild it manually and compare every cell with Word. For a large table, use a converter that explicitly supports GitHub Flavored Markdown tables, export the data separately as CSV, or use MDFold’s Markdown table generator after verifying the source values.

Do not trust the presence of all words as proof that the table survived.

Embedded images can survive in an inconvenient form

The test PNG became Markdown with a data: URL:

![A generated status marker](data:image/png;base64,...)

That makes the image self-contained: no separate file is required. It can also make the Markdown enormous, create unreadable diffs, and fail in publishing systems that block data URLs.

For a repository or documentation site, my preferred workflow is:

extract the image into an assets directory;
give it a stable, descriptive filename;
replace the data URI with a relative path;
preserve or improve the alt text;
preview the page in the actual publishing system.

For example:

![Green deployment status marker](./assets/deployment-status.png)

Mammoth documents inline data URIs as its default image behavior. Other converters may drop images, produce placeholders, or extract separate files. “Images supported” does not tell you which of those contracts a tool provides.

Headers and footers were omitted—and that may be desirable

The difficult DOCX used both:

CONFIDENTIAL DRAFT HEADER
PAGE FOOTER — INTERNAL REVIEW

Neither appeared in the Markdown.

For a web article, this is often desirable. Repeating page furniture is not part of the article’s logical reading flow. For a policy, contract, or controlled document, however, the missing classification, revision, or page note may be important.

The right question is not “did the header survive?” It is “does any information in the header need a new structural home?”

Move essential revision data into front matter, a document metadata block, or the opening section before conversion. Do not rely on page headers to become Markdown automatically.

Underline is ambiguous in Markdown

The underlined sentence returned as plain text.

Markdown has no universal underline syntax, and underlining is often confused with hyperlinks on the web. Mammoth’s default mapping intentionally ignores underline rather than inventing a meaning.

Decide what the underline meant in the source:

emphasis → use *italic* or **bold**;
a section label → use a real heading;
an insertion → write explicit editorial text;
a link → create a real hyperlink;
decoration → remove it.

Conversion cannot make that editorial decision safely.

Convert DOCX to Markdown in a reviewable workflow

Here is the process I would use for a real document.

1. Prepare the Word file

Save legacy .doc files as .docx first.
Apply Heading styles to actual section headings.
Accept or reject tracked changes.
Resolve comments that should not become published content.
Move essential header or footer information into the document body.
Simplify merged tables where possible.
Add useful alternative text to meaningful images.

2. Convert the DOCX

Open MDFold Word to Markdown, choose the .docx file, and wait for editable Markdown to appear. In the version tested on August 2, 2026, the conversion ran in the browser and did not require a document upload endpoint.

3. Check high-risk structures first

Do not begin by proofreading ordinary paragraphs. Check the features most likely to change meaning:

H1, H2, and H3 hierarchy;
first and final paragraphs;
ordered-list numbering;
link destinations;
every table;
image references and alt text;
footnotes, comments, headers, and footers;
names, dates, percentages, and negative numbers.

4. Repair the Markdown for its destination

Different destinations support different Markdown extensions. GitHub Flavored Markdown supports pipe tables, while strict CommonMark does not define the same table extension. A data URI or HTML fragment may work in one renderer and fail in another.

Preview the result where it will actually live: GitHub, a documentation generator, a CMS, an Obsidian vault, or another target system.

5. Download and verify the final `.md` file

Open the downloaded file rather than assuming the editor state and saved artifact are identical. Search for the final checkpoint, inspect the Markdown source, and render it once in the target environment.

The phone-sized workflow worked, but desktop is better for review

I repeated the representative conversion at a 390 × 844 viewport. The file opened, the expected final checkpoint was present, the result remained editable, and the page had no document-level horizontal overflow.

Phone conversion worked in the test. A larger screen is still the better place to compare tables, long links, and image data.

Mobile support is useful for an urgent check. It does not remove the need for a careful desktop review when the source contains complex structure.

When to use a different conversion path

Use this browser workflow for ordinary .docx documents that are mostly headings, paragraphs, emphasis, lists, and links.

Consider Pandoc or another document pipeline when you need:

batch conversion;
repeatable command-line builds;
separate media extraction;
custom style mapping;
footnotes, citations, or richer table handling;
a conversion process that can be reviewed and versioned as code.

Keep Word or export to PDF when the requirement is visual fidelity rather than portable structure.

Privacy is part of the conversion choice

For the tested MDFold workflow, the DOCX was read by browser-side code and the Markdown appeared locally in the editor. That is narrower than claiming that every website conversion is private.

If you use another converter, determine whether the file is uploaded, retained, used for model processing, or logged. This matters for contracts, unpublished research, internal runbooks, customer data, and regulated material.

Local conversion still depends on the device and browser you trust. Extensions, shared computers, managed devices, backups, and downloaded files remain part of the security boundary.

A practical definition of “preserved”

After this test, I would not describe DOCX-to-Markdown quality with one percentage or one checkbox.

I would ask five questions:

Is every important sentence present?
Is the heading hierarchy still correct?
Are relationships—lists, links, tables, notes—still explicit?
Are images usable in the target system?
Did any page-level information need to be moved into document structure?

A converter can automate syntax. It cannot decide what a visual convention meant to the author.

That is why DOCX-to-Markdown conversion should be treated as a small content migration, not a file-extension swap.

DOCX-to-Markdown FAQ

Can I convert an old `.doc` file directly?

Not with the MDFold workflow tested here. Save the legacy file as .docx in Word, LibreOffice, or another compatible editor, then convert the new copy. Keep the original until you have checked the Markdown.

Why did my Word heading become ordinary text?

The paragraph probably looked like a heading without using a Word Heading style. Apply the correct semantic style and convert again; do not rely on font size or bold text alone.

Should I keep embedded images as base64 data?

Only when the destination supports data URLs and a self-contained file matters more than readable source. For repositories and documentation sites, extracted image files with stable relative paths usually produce smaller, reviewable Markdown.

If you have a difficult Word document, try the browser-based converter and share one reproducible feature that did not map cleanly. A merged table, floating text box, tracked-change sequence, or image-heavy page is more useful feedback than “formatting broke.”

How to Convert Markdown to a Professional PDF (Without Broken Tables, Code, or Math)

frank — Wed, 29 Jul 2026 14:11:00 +0000

Converting Markdown to PDF is easy.

Converting it into a PDF you can confidently send to a client, reviewer, professor, or teammate is a different task.

A successful export needs more than a Download PDF button. The document should have a clear hierarchy, readable typography, code that does not disappear off the page, tables that fit, working links, and equations that survive the transition from source text to fixed pages.

This guide gives you a complete workflow using MDFold’s Markdown to PDF converter. It also explains the failure cases that matter, including wide tables, long code lines, missing background colors, awkward page breaks, and content that should not be exported as PDF in the first place.

I tested the workflow with headings, task lists, a numeric table, JavaScript, links, inline math, and a display equation on both desktop and a 390-pixel-wide phone viewport.

First decide whether PDF is the right output

PDF is a good destination when the document is finished and its appearance should remain stable.

Use PDF for:

project reports and technical proposals;
resumes and portfolios;
assignments and research notes;
release plans and operational runbooks;
documents that will be printed, signed, archived, or attached to email;
anything where the recipient should read rather than rewrite.

Do not default to PDF for every document.

What the recipient needs to do	Better format
Read, print, archive, or approve a finished document	PDF
Edit wording, comment, or use tracked changes	Word
Publish content on a website	HTML
Continue writing in a repository or notes app	Markdown
Share a short visual card on social media	PNG or JPG

This decision prevents a common mistake: spending time forcing an editable workflow into a fixed-page format.

Start with Markdown that has real structure

A converter can style your structure, but it cannot reliably invent structure that is missing.

Before exporting, check that the source has:

one H1 for the document title;
H2 sections for the main ideas;
H3 headings only when they belong inside an H2 section;
blank lines around lists, tables, blockquotes, and code fences;
language names on fenced code blocks;
meaningful link text instead of repeated “click here” labels;
concise table cells;
image URLs that the browser can actually load.

Here is the representative document I used for testing:

# API Reliability Review

**Owner:** Platform Team  
**Status:** Ready for review

> Goal: reduce failed requests without hiding operational risk.

## Release checks

- [x] Retry policy documented
- [x] Error budget reviewed
- [ ] Final approval

| Metric | Current | Target |
|---|---:|---:|
| Availability | 99.92% | 99.95% |
| P95 latency | 280 ms | 220 ms |

## Example

```javascript
const retry = (attempt) =>
  Math.min(1000 * 2 ** attempt, 30000);
```

Inline formula: $E = mc^2$

$$
S = \sum_{i=1}^{n} x_i
$$

[Open the runbook](https://example.com/runbook)

This is a better test than a document containing only headings and paragraphs. It exercises the parts most likely to fail when content moves onto fixed pages.

Convert Markdown to PDF in five steps

1. Open or paste the Markdown

Open the Markdown to PDF converter.

You can type directly in the editor, paste existing Markdown, or use Open MD to select a .md, .markdown, or .txt file.

Do not style the document yet. First, confirm that the content itself is complete. Check the title, section order, links, table values, code, and equations.

2. Review the live preview before choosing a template

The preview should show the document’s logical structure:

the title is visually distinct;
section levels are obvious;
task-list states are recognizable;
numeric columns align correctly;
code appears as code rather than ordinary prose;
inline and display math render;
the link remains identifiable.

Keep the source and preview visible together while correcting structure. Styling a broken hierarchy only makes the problem more attractive.

During my test, the preview preserved the title, metadata labels, blockquote, three task items, two-row table, JavaScript block, link, and both equation forms.

3. Choose a template for the reader, not for decoration

MDFold currently provides 24 document styles grouped into business, minimal, academic, technical, and creative categories.

Choose according to the job:

Document	Good starting direction	Why
Technical report or runbook	GitHub Style, Modern, or another restrained technical style	Strong code contrast and familiar hierarchy
Proposal or client report	Classic, Business Gray, or Corporate Blue	Conservative presentation and clear sections
Essay or research note	Research Journal, Academic Green, or a readable serif style	Comfortable for longer reading
Resume	Simple, Pure Black & White, or Soft Ink	Keeps attention on content
Announcement or short handout	A restrained creative style	Adds identity without overwhelming the message

The rule is simple: the template should make the document easier to understand. If the reader notices the theme before the content, reduce the decoration.

4. Adjust typography and spacing only when the preview shows a problem

Use Edit template to adjust colors, body and heading fonts, type size, line height, and page padding.

Make one change at a time and look for a specific improvement:

reduce the body size slightly when a dense table barely overflows;
increase line height when long paragraphs feel crowded;
reduce page padding when code needs a little more horizontal room;
increase code contrast if punctuation is hard to distinguish;
use a calmer accent color for formal documents;
keep body text dark on a light background for print-heavy use.

Avoid shrinking everything to rescue one difficult element. A table that needs unreadably small body text should be simplified or split instead.

5. Download, save as PDF, and inspect the artifact

Click Download PDF. MDFold prepares the print-focused document and opens the browser’s print dialog. Choose Save as PDF as the destination.

The final controls depend on your browser and operating system. Browser printing can apply print-specific styles, page dimensions, orientation, and margins; this is part of the standard web printing model described by MDN’s printing guide.

Before saving:

Confirm the destination is Save as PDF.
Check the page size and orientation.
Review the page count.
Enable Background graphics if template colors or code shading are missing.
Inspect a page containing a table or code block.
Save the PDF.
Open the saved file in a PDF reader and repeat the critical checks.

The last step matters. The saved PDF is the deliverable; the browser preview is only evidence of what you expect to receive.

Fix the failures that appear in real documents

A wide table runs beyond the page

Markdown tables describe rows, columns, and alignment. They do not define a print layout.

Fix the source in this order:

Shorten verbose column headings.
Replace paragraph-length cells with short phrases.
Remove columns that are not needed by this audience.
Split one large table into two focused tables.
Reduce page padding slightly.
Use landscape orientation if the print dialog provides it.

Do not solve every table problem by reducing the font until nobody can comfortably read it.

Long code lines are clipped or create horizontal scrolling

PDF pages have a fixed width. A long command, URL, string, or generated line cannot expand the page.

Prefer readable source:

const retryDelay = Math.min(
  baseDelay * 2 ** attempt,
  maximumDelay,
);

Instead of:

const retryDelay = Math.min(baseDelay * 2 ** attempt, maximumDelay);

For commands or output that cannot be wrapped safely, use a smaller code font, shorten the example, or move the complete version to a linked repository.

Code backgrounds disappear in the saved PDF

Enable Background graphics in the browser print dialog.

Browsers often treat printed output differently from screen output. The saved result can therefore omit a background that was visible in the live preview unless printing backgrounds is enabled.

After changing the setting, inspect one code-heavy page before saving the complete document.

A heading is stranded at the bottom of a page

Page breaks are calculated from the final type size, spacing, margins, and content.

Try these fixes:

shorten the paragraph before the heading;
reduce excessive spacing;
move a related sentence into the next section;
split an oversized table or code block;
choose a slightly more compact template.

Avoid inserting a series of blank lines. Blank lines are content, not reliable page-break instructions, and they become fragile when the document changes.

An image is missing or blurry

For a remote image, open its URL in a browser first. If the browser cannot load it, the converter cannot render it into the preview.

Use an image large enough for its displayed size, but do not insert an enormous source just because the final page is small. Check that diagrams remain legible in the saved PDF at normal zoom.

If the document must work offline or the image URL requires authentication, replace it with a stable accessible source before exporting.

A formula does not render

The page renders supported math notation with KaTeX. KaTeX documents its available commands in the official supported-functions reference.

Check:

inline math uses single dollar delimiters;
display math uses double dollar delimiters;
backslashes were not removed while copying;
the command is supported;
braces are balanced.

Even when a formula renders correctly, inspect its width. A long display equation may need to be split across lines or rewritten before it can fit a portrait page.

A link looks right but opens the wrong destination

Click important links in the preview before export, then test them again in the saved PDF.

Use descriptive text:

[Read the deployment runbook](https://example.com/runbook)

This is more useful than:

[Click here](https://example.com/runbook)

If the PDF may be printed, consider whether the destination also needs to appear in a references section.

Use this 60-second preflight before sending the PDF

Do not reread every sentence through the converter interface. Review the artifact systematically.

Check	What to inspect
First page	Title, author or owner, date, and opening hierarchy
Structure	H2/H3 order, list indentation, blockquotes, and section flow
Numbers	Table values, percentages, dates, and formulas
Code	Wrapping, indentation, contrast, and missing characters
Images	Loading, sharpness, captions, and page fit
Links	Important destinations in the saved PDF
Pagination	Stranded headings, nearly blank pages, split tables, and clipped content
Final page	Truncation, accidental notes, and expected closing content

For legal, financial, medical, academic, or compliance-sensitive material, compare critical quotations, numbers, formulas, and references against the source. Conversion saves formatting work; it does not replace responsibility for the content.

What happens to your Markdown

In the version tested for this article, editing, rendering, template selection, and print preparation happened in the browser. The Markdown did not need to be uploaded to a conversion server.

The browser and operating system handle the final Save as PDF step.

This is useful for private drafts, source code, internal documentation, and unpublished reports, but “local” does not make the surrounding environment automatically safe. A compromised device, untrusted browser extension, publicly shared computer, or remote image URL can still create privacy risks.

Use non-sensitive image sources, keep the browser updated, and follow your organization’s document-handling rules.

Mobile works for editing and review, but desktop is better for final pagination

At a 390 × 844 viewport, MDFold showed separate Write and Preview controls. The test document’s table and equations remained accessible without page-level horizontal overflow.

The phone layout is useful for corrections and preview checks. A larger screen remains more comfortable for reviewing page breaks and wide tables.

Use mobile when you need to correct wording, inspect a short document, or produce a quick export. Use a desktop or tablet for long reports, detailed template adjustment, and final pagination review.

Frequently asked questions

Does MDFold create the PDF directly?

MDFold prepares the document and opens the browser print dialog. Select Save as PDF there. Available page sizes, orientations, margins, headers, footers, and background options depend on the browser and operating system.

Can Markdown tables, code blocks, and math be exported?

They appeared in the live preview during the representative test for this article. Difficult content still needs inspection: wide tables and long code can exceed the printable width, and long equations may need rewriting.

Why does my saved PDF look different from the preview?

Check the selected printer or destination, page size, margins, scale, orientation, and Background graphics setting. Print settings affect the final file.

Can I use custom HTML inside Markdown?

Do not assume arbitrary HTML or browser-specific styling will survive every Markdown renderer and print path. Prefer standard Markdown for portable documents, then verify any custom HTML in both the preview and saved PDF.

Is Markdown to PDF private?

The MDFold workflow tested for this article handled the Markdown and print preparation in the browser. You should still consider device security, browser extensions, remote images, and your organization’s rules for sensitive documents.

The real goal is not conversion—it is a trustworthy artifact

A good Markdown-to-PDF workflow is:

choose PDF only when the document is ready for fixed presentation;
give the Markdown a clear structure;
test difficult content, not only paragraphs;
choose typography for the reader;
inspect the print settings;
open and verify the saved PDF.

That process takes a little longer than clicking Download, but it prevents the failures people actually notice after you send the file.

Try the workflow in the free MDFold Markdown to PDF converter.

If you find a table, code sample, equation, or page-break case that does not behave as expected, share the smallest Markdown example that reproduces it. A reproducible edge case is far more valuable than a vague “the formatting looks wrong.”

I Shipped a Privacy-First Markdown Converter in 3 Days. Here’s What the Launch Post Usually Leaves Out

frank — Tue, 28 Jul 2026 16:18:11 +0000

Most launch posts follow the same script:

I had an idea, built it quickly with AI, shipped it, and here is the feature list.

That is the clean version.

The useful version includes the wrong assumptions, the features that were deliberately cut, the conversions that looked correct until I opened the downloaded file, and the uncomfortable fact that “works on my machine” is not the same as “works for a stranger.”

So this is the useful version.

I built MDFold, a free set of browser-based tools for moving documents into and out of Markdown. The first working version took three days. It now handles eight practical workflows:

PDF to Markdown
Markdown to PDF
Markdown to Word
Word to Markdown
Markdown to HTML
HTML to Markdown
Markdown to PNG or JPG
Visual and CSV-based Markdown table generation

No account is required, and the conversion work happens in the browser.

But those bullet points are the least interesting part of the story.

The original idea was too broad

My first mental model was simple: “convert Markdown to anything.”

It sounded focused. It was not.

Every output format carries a different promise:

A Word document should remain editable.
A PDF should be visually stable and printable.
HTML should be clean enough to publish or reuse.
An image should be sharp at the dimensions the user selected.
Markdown extracted from PDF, Word, or HTML should be readable, not merely technically valid.

A universal Convert button would have hidden those differences. It also would have produced a product that was easy to demo and frustrating to use.

The first important decision was therefore not about code. It was to give each workflow its own interface and success criteria.

Markdown to PDF needs page preview and print-aware styling. Word to Markdown needs a cleanup step. A table generator needs row, column, alignment, paste, and CSV controls. Treating these as one feature would have made every workflow worse.

The lesson: scope is not the number of pages you build. Scope is the number of promises you make.

Privacy changed the architecture, not just the copy

“Privacy-first” is easy to place under a logo. I wanted it to describe observable behavior.

In MDFold, the document content stays in the current browser during editing, preview, conversion, and export. There is no upload step for the converter to work. Saved preferences and reusable templates stay on that device as well.

That choice created useful constraints:

There is no upload queue.
A slow connection does not become a slow conversion after the app has loaded.
The server does not need to store a stranger’s report, contract, draft, or source code.
Clearing browser data can remove locally saved preferences and templates.
Moving to another device does not automatically bring those local settings with you.

The last two points matter. Local storage is a privacy advantage, but it is not cloud sync. A trustworthy product should explain both sides of that trade-off.

This also gave me a simple product test: if a conversion required sending the document to an application endpoint, the implementation had broken the product promise.

The editor became the product

I originally thought of the editor as a place to paste input before clicking a button.

That was wrong.

Conversion is rarely a one-click event. People notice a heading that should be smaller, a table that is too wide, an image that needs a better URL, or a code block with a missing language label. They need a correction loop:

Write, paste, or open the source.
Inspect the result.
Fix the source or presentation.
Export.
Open the exported file and verify it.

MDFold therefore uses a live editor and preview instead of an upload form followed by a download screen.

The source and output remain visible together, so formatting problems can be fixed before export.

This led to several features that did not look essential in the first sketch but became important in real use:

focus mode for long editing sessions;
fullscreen mode for detailed review;
quick actions for headings, code, lists, and tables;
24 document themes across business, minimal, academic, technical, and creative styles;
editable colors, fonts, type size, line height, and page spacing;
a short first-use tour that can be dismissed and reopened;
separate write and preview views on a phone-sized screen.

None of these is impressive in isolation. Together, they shorten the correction loop.

That is a better product goal than maximizing the feature count.

“It rendered” was not a sufficient test

The biggest trap in document tools is trusting the preview.

A preview can look perfect while the downloaded file is malformed. A file can download successfully and still be unreadable by the program the user opens next.

I used a representative Markdown document containing:

H1, H2, and H3 headings;
bold and italic text;
ordered and unordered lists;
links and blockquotes;
a table;
a fenced JavaScript block;
inline and block math;
an external image.

Then I checked the output according to the format:

Output	What I checked
DOCX	The file is a readable Word archive and the document structure is present
HTML	Headings, rich text, links, code, and table markup are present
PNG	The downloaded image has the requested dimensions and remains sharp
JPG	The file is a valid JPEG rather than renamed PNG data
PDF	The print preview, pagination, background styling, and save control work
Markdown	Reading order and useful structure survive the source conversion

I also tested the rendered site, not only the individual conversion functions. The current check covers the homepage, all eight tools, the tools directory, and the practical guides.

This caught a class of problems that unit-level checks miss: a converter can be correct while its route fails to render, its first-use overlay blocks the download button, or its phone layout creates horizontal overflow.

The lesson: test the artifact in the program that will consume it, and test the complete user path that creates it.

PDF to Markdown forced me to be honest

PDF is a presentation format. Markdown represents document structure. Moving from one to the other requires inference.

A digitally generated PDF with a clear reading order may convert into useful Markdown. A multi-column layout can scramble that order. A scanned PDF may contain no useful text layer at all. Complex tables, positioned captions, footnotes, and decorative layout can require cleanup.

A successful extraction still needs a human check for reading order, headings, tables, and missing content.

I could have hidden those limitations behind “AI-powered” language or claimed support for every PDF. That might improve a landing-page headline, but it would make the product less useful.

MDFold instead gives the extracted Markdown back in an editor. The user can inspect the text order, correct headings, repair a table, and compare the preview before downloading.

Some files need OCR. Some need manual cleanup. Some are better handled by a specialized document-reconstruction tool.

Saying that clearly is part of the feature.

AI accelerated implementation, but it did not own the decisions

I used AI-assisted development throughout the build. It was especially helpful for:

generating a first implementation from a precise interface specification;
applying the same behavior across several converter pages;
proposing test cases;
finding inconsistent labels and repeated layout problems;
turning a failure into a reproducible check.

It was less useful when the instruction was vague.

“Make the converter better” produces plausible changes.

“At 390 × 844, the first-use guide must not create horizontal overflow; the editor, preview switch, and download action must remain reachable” produces work that can be judged.

The speed did not come from asking an AI to build an entire product in one prompt. It came from repeatedly doing four things:

Define one observable outcome.
Implement the smallest coherent change.
Run the real workflow.
Keep the failure as a permanent check.

AI made each loop faster. It did not remove the need for the loop.

The redesign happened after the product worked

My first version was functional, but the interface still made people work too hard to understand it.

The tools were not visible early enough. Example content looked too much like user content. Long documents needed more space. First-time users needed guidance, but a large welcome dialog would interrupt returning users.

The fixes were small and specific:

move the actual workspace higher on the page;
label bundled content as an example;
add editor focus and fullscreen modes;
show a brief guide only on the first converter visit;
remember dismissal locally;
keep a “Quick tour” control for anyone who wants it again;
make the phone layout switch cleanly between writing and previewing.

The most valuable design work was not adding visual decoration. It was removing moments of uncertainty.

What I deliberately did not build

Fast shipping only works when “not now” is a real answer.

I left out:

accounts;
cloud document storage;
cloud template synchronization;
payments and subscription tiers;
team workspaces;
an opaque “AI cleanup” button;
a promise of perfect conversion for every source file.

These features may make sense later. In the first release, they would have expanded the security surface, privacy explanation, support burden, and number of states that needed testing.

The free, accountless product is not a temporary gap in front of the real product. It is the simplest complete version of the promise: open a tool, convert a document, inspect the result, and leave with a usable file.

What I would do differently

If I started again, I would make three changes.

1. Write the acceptance tests before the interface

“Supports Markdown tables” is vague.

“A table with alignment markers, inline emphasis, and a long cell remains readable in preview and export” is a test.

Starting with the second sentence would have prevented several rounds of polishing the wrong thing.

2. Build difficult sample files on day one

A friendly demo document gives false confidence. Every converter needs a representative file and an adversarial one.

For MDFold, that means wide tables, long code lines, nested lists, broken image URLs, non-Latin text, scanned PDFs, multi-column PDFs, and Word files with inconsistent styles.

3. Treat explanations as part of the interface

Users need to know why a scanned PDF produces little text, why PDF background colors can depend on a print setting, and why local templates do not appear on another device.

A clear limitation at the right moment prevents more frustration than another generic feature badge.

Three principles I am keeping

After building and revising MDFold, these are the principles I would carry into any small developer tool:

Every format is a separate promise. Define what a successful output means before implementing it.
Privacy must be visible in the data flow. “We care about privacy” is not a substitute for knowing where the file goes.
The exported artifact is the product. A beautiful preview does not rescue a broken download.

The first version took three days. Making it trustworthy is an ongoing process of finding vague promises and replacing them with specific behavior and repeatable checks.

You can try MDFold without creating an account.

If you test it, I would especially value one kind of feedback: what file or Markdown construct produced a result you did not expect?

That is more useful than “looks great,” and it gives me the next real test case.`