Eight document converters in, "convert" was the easy word — flavor compatibility was the hard one

Eight document converters in, "convert" was the easy word — flavor compatibility was the hard one

I've shipped converters for PDF, DOCX, PPTX, XLSX, EPUB, HTML and raw URLs, and the lesson that keeps repeating is that nobody wants a Markdown output — they want their Markdown output.

My first HTML-to-Markdown version emitted ATX headings (# Title) and - bullets. It worked on every test file I threw at it. Then a downstream agent piped the output into a parser that only understood setext headings (Title\n=====) and every heading silently became body text. Another pipeline broke on * emphasis delimiters instead of _. Another choked when tables came back without a header separator row. None of these were bugs in the converter — they were mismatches between one opinionated output and many opinionated consumers.

So I stopped shipping one canonical flavor and started exposing the knobs: heading style, bullet marker, code block style, emphasis delimiters. The converter got dumber and more configurable, and the breakage moved from my code into the caller's config where it belonged. Same story with spreadsheets — flattening multi-sheet workbooks into sheet order only made sense until a consumer needed sheet names preserved to disambiguate duplicate headers.

The meta-lesson for anyone shipping in this space: your API's output format is an interface, and interfaces have versioning costs. If you can, make the format negotiable per call instead of per release. I ended up packaging the whole suite — auto-detect included — as https://x402.freeq.one/tools/document_to_markdown.html, mostly so I never have to explain "which flavor do you need?" in an issue thread again.