Why Structure Matters Before Conversion
FlyingMouse Format’s text and document paths reveal why conversion quality is decided before a destination file is rendered. This chapter focuses on the project’s use of structural intermediates, strict parsing, and bounded resource handling, so that a reader can distinguish a document transformation from a sequence of text substitutions. The practical judgment is straightforward: if headings, tables, code, formulas, images, and quoted data have different meanings, they must be recognized as different things before they can be preserved.
A document is more than its visible characters
A naive converter can appear to work by changing punctuation or replacing one set of markers with another. Remove a few heading symbols, split text at newlines, and the output may look plausible for a short sample. The approach breaks as soon as the same characters mean different things in different contexts. A line beginning with # may be a heading in ordinary Markdown but literal content inside a code block. A comma may separate CSV fields, belong to a quoted value, or appear alongside a line break inside one field. Asterisks can mark emphasis or be the exact text a programmer wants to preserve.
FlyingMouse Format addresses this problem by giving the document an intermediate representation. Instead of treating the input as one undifferentiated string, its Markdown document path asks Pandoc to parse the source into a structured document tree. The converter can then visit nodes—headings, paragraphs, links, images, code, formulas, and other blocks—before rendering the transformed tree into a DOCX. The result is not that every source feature is magically supported. It is that each supported feature has a place in the transformation, and unsupported material can be qualified instead of accidentally rewritten.
The HTML and Office-to-Markdown paths use a related principle. A shared Turndown configuration emits ATX-style headings and fenced code blocks, and table handling distinguishes ordinary tables from more complicated structures involving nested tables or row and column spans. That distinction matters because a simple rectangular table can map naturally to Markdown pipes, while a complex table may need retained HTML or a warning rather than a false claim that its layout has been preserved.
The intermediate representation creates an explicit boundary between three actions. Parsing determines what the source means according to the supported grammar. Transformation decides which semantic elements have an equivalent in the destination. Rendering writes the destination syntax or package. When those stages are collapsed into a global regular expression, the converter cannot tell whether it is changing a document element or corrupting a literal value.
The difference is not academic. It changes how a converter behaves when a source is incomplete or unusual. A structural path can preserve a code block as code, keep a link’s text if its address is unsafe, and return a warning when a raw HTML or TeX construct cannot be translated. A line-oriented path tends to produce a clean-looking file while hiding what it misunderstood.
The flow has two kinds of uncertainty. A resource may be unavailable even when the surrounding document is understandable. A semantic node may have no safe or supported equivalent in the target. Both should remain visible in the output’s warnings, because a successful file write is not evidence that every source meaning made the journey.
Pandoc provides structure, not a blank cheque
FlyingMouse Format uses offline Pandoc as a document engine for the Markdown-to-Word route. The project parses Markdown into Pandoc’s JSON representation, applies controlled transformations, and asks Pandoc to render the resulting tree as DOCX. This makes the conversion more robust than deleting Markdown markers from the final text. Headings can become heading styles, tables can become Word tables, nested lists can remain nested, and mathematical expressions can be represented as editable Word math rather than flattened image-like text.
The source also handles code and mathematics with care. Code is not sent through formula normalization, so characters that look like formatting or math inside a code block remain literal. Supported formulas can become editable Office math structures, while unsupported raw HTML or TeX is preserved as literal content with a warning rather than executed or silently discarded. That is a strong but bounded promise: the converter can preserve and transform the constructs it understands without claiming to implement every web layout, TeX macro package, or diagram language.
Resource handling is part of the structural model. An image in a Markdown document is not only a URL string; it is a request to read or embed a particular resource. The converter accepts embedded images and local images supplied with the source document, checks that a local path remains inside the source directory, and limits accepted image types. If an image is missing, remote, outside the permitted directory, or otherwise unsupported, the document keeps an explanatory description and the conversion reports an unavailable-image warning. It does not silently connect to the network or search arbitrary locations on the user’s disk.
This choice can feel less convenient than a browser. A web page can often fetch a remote image and display it; a local conversion tool that promises predictable offline behavior should not make that network access invisible. The warning is therefore part of the result’s meaning. It tells the user that the document’s text survived but one visual resource did not. The same distinction matters when an Agent or CLI saves the output: automation can react to a stable warning instead of assuming that a successful process means a complete document.
Metadata is bounded in the same way. Ordinary document information such as title, author, date, language, and keywords can be retained, while unsupported metadata instructions are not allowed to become an uncontrolled template or filter mechanism. The converter treats document content as data to transform, not as a set of commands to execute. That separation is both a fidelity choice and a security boundary.
The user-facing strength of this design is selective preservation. A Markdown file does not need to be accepted or rejected as a single indivisible object. A heading can convert correctly while a raw macro is retained literally. A local image can be embedded while a missing image is described. A code block can keep its exact characters while a surrounding paragraph receives normal formatting. The output can be useful without pretending that all input features have equivalent destinations.
An intermediate tree also gives the project something concrete to validate. The 0.7.0 audit does not stop at checking that a DOCX is a ZIP package or that an HTTP request returned success. It checks selected outputs for heading styles, Word tables, nested numbering, hyperlink relationships, underline and highlight formatting, and editable Office math structures. It also renders selected documents through LibreOffice and inspects the resulting pages. Those checks do not prove that every Word or WPS environment will display every font or layout identically, but they test the important claim at the level where a user experiences it: structure in the document package and appearance in a rendered document.
This is a useful distinction between a good intermediate and a good conversion. The tree can preserve a heading as a heading, yet a downstream writer might place it in the wrong style. A formula can be represented as editable math, yet a particular renderer might expose a limitation. A local image can be safely found, yet its dimensions or format can still make embedding fail. Structural parsing makes these failures diagnosable; it does not remove the need to inspect the destination. The conversion contract becomes stronger when parsing, transformation, rendering, and output checks are treated as separate evidence-producing stages.
CSV demonstrates why “simple” data needs strict rules
CSV looks simpler than a formatted document because it has fewer visible conventions. In practice, its ambiguity is concentrated in places that line-based parsers routinely mishandle. Fields can contain commas, quoted values can contain line breaks, a byte-order mark can appear at the beginning of the file, and rows can have inconsistent numbers of columns. A converter that splits every line and then every comma may produce rows that look orderly while moving values into the wrong columns.
FlyingMouse Format uses a strict CSV parser for its CSV-derived paths. It recognizes a byte-order mark, honors quoted fields and embedded newlines, refuses relaxed quote handling, and rejects inconsistent column counts instead of improvising. It also checks headers for duplicates and for unsafe object-like names that could create surprising behavior when records are represented as JavaScript objects. These checks are not decorative validation. They prevent a malformed or adversarial input from being treated as a clean data model.
The same parsed records can then be directed to different destinations: Markdown tables, HTML tables, JSON objects, spreadsheets, or PDF through an intermediate representation. Each destination has its own presentation rules, but the source parsing happens before those rules are applied. A quoted newline remains part of the original field rather than becoming an accidental new row. A pipe in a Markdown cell can be escaped rather than mistaken for a column boundary. A malformed record can stop with a stable parse error instead of producing a misleading partial table.
There is a trade-off in failing closed. A permissive parser may return something quickly from damaged input, and the user may prefer any result to an error. The cost is that the user cannot easily tell whether the output reflects the source or the parser’s guesses. FlyingMouse Format’s stricter behavior gives up some opportunistic recovery in exchange for a more defensible relationship between input and output. For data conversion, a visible failure is often safer than a spreadsheet that silently shifts a column.
This is also where structure and security meet. A parser that understands quoting reduces data corruption, while header checks reduce the chance that input fields acquire unintended meaning inside the application’s own object model. The project is not claiming that every parser risk disappears; it is choosing explicit grammar and bounded names over the convenience of treating arbitrary text as executable structure.
A strong subset can be more honest than universal syntax
The project’s Markdown support illustrates a useful product discipline. It can preserve headings, tables, nested lists, code, links, local images, and supported formulas through defined paths. It does not promise every HTML fragment, CSS rule, TeX macro, Mermaid diagram, or network resource. That boundary is not a confession that structural conversion failed. It is the condition that makes the supported subset understandable.
The distinction matters because “Markdown” is not one perfectly fixed language once real documents enter the picture. Authors use dialect extensions, embedded HTML, custom attributes, mathematical notation, diagram blocks, and links to resources whose availability depends on the surrounding folder or the network. A converter that claims complete support without naming its grammar would force the user to discover the boundary by inspecting damaged output. FlyingMouse Format instead keeps unsupported material literal or warns about it, allowing the reader to decide whether the remaining work is acceptable.
The same reasoning applies to the application’s multiple access paths. The UI can remember a target for a normalized source extension, and the CLI can ask for machine-readable capabilities, but neither preference changes what the structural converter understands. Convenience can reduce repeated choices; it cannot manufacture a missing semantic mapping. The shared conversion contract remains the source of truth.
The core lesson is therefore broader than Markdown or CSV. Structure is a controlled promise. It tells us what the converter believes the input contains, what the destination can express, and where the two models do not line up. A semantic intermediate makes that relationship inspectable. Strict parsing makes the input boundary visible. Warnings and literal fallbacks preserve uncertainty instead of burying it in a polished-looking file.
That lesson becomes more demanding when the source is a PDF. A PDF may display paragraphs and tables while storing positioned text and drawing instructions rather than editable document semantics. The next case asks what happens when FlyingMouse Format must reconstruct those semantics instead of translating a structure it already has.