Technical Article

PDF to Markdown and DOCX Export in Delphi

Half a point decides it. In a report with 10-point body text, a section title set in 11-point bold converts to Markdown as an ordinary paragraph, while a 12-point caption on the cover, in a regular weight, comes back as ### Quarterly figures. That looks backwards until you remember what a PDF page actually stores: glyphs at coordinates, a font name and a size. Nothing on the page says 'heading'. Every heading a converter emits is a guess built from those three facts, and the guess has thresholds

Why a PDF page has no paragraphs to export

A PDF page contains text-showing operators, not paragraphs. Each operator places a run of glyphs at a position, in whatever order the producing application happened to emit them, and ISO 32000-1 places no obligation on the producer to say that two runs belong to the same sentence, let alone the same list item or table cell. The format describes a printed page exactly, and it gets there by throwing away the structure that produced the page

So every converter rebuilds what the generator discarded. Lines come from shared baselines and vertical spacing. Paragraph breaks come from changes in spacing and indentation. A list is a run of blocks that start with a bullet character or a number pattern. A table is a grid of text blocks whose edges line up across rows and columns. On documents that follow ordinary typographic habits this works well; on a brochure laid out for visual effect it has very little to hold on to

PDF Library for Delphi diagram of the inference pipeline that turns raw PDF glyph runs into grouped lines, paragraphs, headings, lists and tables exported as Markdown or DOCX
Every heading, list and table in the export is inferred from spacing, fonts and aligned edges because the PDF format itself records none of them

Tagged PDFs are the big exception. When a document carries a structure tree, the paragraph, heading, list and table roles are recorded by the producer instead of guessed afterwards, which is why the work described in tagged PDF accessibility structure also pays off in conversion quality. If you control the producer, tagging the output is the cheapest thing you can do for whoever converts it later

Where the heading levels come from

PDF Library for Delphi decides heading levels in two ways, depending on the input. On a tagged page, a block whose structure role is H1 through H6 keeps that level, and H or Title becomes level 1. On an untagged page the export falls back to font size relative to the page's body text, and it only considers single-line paragraphs of 200 characters or fewer

The size rule needs both a ratio and an absolute gap, measured against the dominant body size:

Markdown outputLargest text on the lineWith a 10 pt body
#at least 1.6 times the body size and at least 4 pt larger16 pt and up
##at least 1.35 times and at least 2.5 pt larger13.5 pt and up
###at least 1.15 times and at least 1.25 pt larger11.5 pt and up

That explains the opening example. An 11-point bold title over 10-point text misses the third tier by half a point, and weight plays no part in the level. The cover caption at 12 points clears it. The absolute gap exists for small body sizes: on 6-point footnote-sized text a ratio alone would promote a 7-point line to a heading, and the extra 1.25 pt requirement stops that

We think this is the right trade. Bold is far too common inside body text (lead-in phrases, defined terms, totals in a summary line) to be a reliable heading signal on its own, and a converter that promotes every bold line produces Markdown with dozens of spurious sections. Missing a few bold-only headings costs less. If your documents rely on bold-at-body-size titles, the reliable fix is upstream: tag them, or bump the title size by a point and a half

Bold and italic in the output are read from the font name. A run whose font name contains Bold, Black or Demi becomes **bold**; Italic or Oblique becomes *italic*. Producers that subset fonts under opaque names such as F3, or that fake bold by stroking regular glyphs, give the export nothing to read, and that text arrives unstyled

Markdown export for retrieval pipelines

The Markdown path is the one to reach for when the destination is a text pipeline: a documentation site, a search index, a chunked corpus for an assistant. ExportPageMarkdown returns one page as a WideString, ExportDocumentMarkdown returns a page range, and SaveMarkdownToFile and SaveMarkdownToStream write the same text as UTF-8 without a byte-order mark. The missing BOM is deliberate; a number of static site generators and diff tools treat it as content

PDF Library for Delphi diagram of Markdown export where the options bitmask selects page markers, heading detection and style preservation before the whole page range is built and written once as UTF-8
Options combine as a bitmask and the writer emits UTF-8 without a BOM, while page markers leave every retrieved chunk a citable page number

Options are a bit mask: PDF_MARKDOWN_INCLUDE_PAGE_MARKERS (1), PDF_MARKDOWN_DETECT_HEADINGS (2) and PDF_MARKDOWN_PRESERVE_STYLES (4), with PDF_MARKDOWN_DEFAULT combining all three. A second, document-wide setting controls the analysis itself: SetStructuredTextOptions takes the PDF_STRUCTURED_* flags, and its default detects columns, detects running headers and footers, and joins tables that continue across a page break

uses
  SysUtils, PDFlibrary;

var
  Pdf: TPDFlib;
  Exported: Integer;
begin
  Pdf := TPDFlib.Create;
  try
    if Pdf.LoadFromFile('handbook.pdf', '') = 0 then
      raise Exception.Create('Cannot open handbook.pdf');

    // Detection of running headers and footers is on by default;
    // adding EXCLUDE_FURNITURE also drops them from the output
    Pdf.SetStructuredTextOptions(PDF_STRUCTURED_ADVANCED_DEFAULT or
      PDF_STRUCTURED_EXCLUDE_FURNITURE);

    // Page markers and headings, but no ** and * emphasis
    Exported := Pdf.SaveMarkdownToFile('1-40',
      PDF_MARKDOWN_INCLUDE_PAGE_MARKERS or PDF_MARKDOWN_DETECT_HEADINGS,
      'handbook.md');
    if Exported = 0 then
      raise Exception.CreateFmt('Markdown export failed, error %d',
        [Pdf.LastErrorCode]);

    // JSON with one entry per page: readingSource is tagged, mixed,
    // geometric or geometric-columns
    Writeln(Pdf.GetLastStructuredTextDiagnostics);
  finally
    Pdf.Free;
  end;
end;

For a retrieval corpus we drop PDF_MARKDOWN_PRESERVE_STYLES. Emphasis is applied run by run, so a bold phrase set in several runs comes out as **Net** **revenue**, which reads fine on screen and adds noise to every embedding. Page markers are the opposite case: keep them. Each marker is an HTML comment, <!-- page: 12 -->, invisible when the Markdown is rendered and trivial to parse when you split chunks, so a retrieved passage can cite the page it came from. When a table runs on from the previous page, the marker for the new page is left out so the pipe table stays in one piece

Two behaviours catch people who export page by page in a loop. First, running headers are recognised by repetition: a paragraph in the top or bottom 12 percent of the page counts as furniture when matching text sits in the same band on another page of the same export, with digits normalised so 'Page 3 of 40' matches 'Page 4 of 40'. A single-page call has no other page to compare against, so an untagged running header stays in the text. Second, images in Markdown are embedded inline as data: URIs, which keeps the file self-contained and means a page with a large photograph can add hundreds of kilobytes of base64 to the file. If your chunker has a size limit, strip lines starting with ![PDF image before splitting

Keeping Markdown and DOCX option flags apart

The Markdown and DOCX constants share the low bits but mean different things. PDF_DOCX_INCLUDE_IMAGES is 1, the same value as PDF_MARKDOWN_INCLUDE_PAGE_MARKERS. Pass the DOCX constant to a Markdown call and the compiler is happy, the call succeeds, and you get page markers. Only a bit outside the Markdown range is rejected:

var
  Md: WideString;
begin
  // Compiles and runs: 1 is read as PDF_MARKDOWN_INCLUDE_PAGE_MARKERS
  Md := Pdf.ExportDocumentMarkdown('', PDF_DOCX_INCLUDE_IMAGES);

  // PDF_DOCX_PRESERVE_PAGE_BREAKS is 8, outside the Markdown mask:
  // Md comes back empty and LastErrorCode is 113
  Md := Pdf.ExportDocumentMarkdown('', PDF_MARKDOWN_DEFAULT or
    PDF_DOCX_PRESERVE_PAGE_BREAKS);
  if (Md = '') and
     (Pdf.LastErrorCode = PDFLIB_ERROR_MARKDOWN_EXPORT_INVALID) then
    Writeln('Unknown Markdown option bit');
end;

An empty string is also a legitimate result for a page with no text at all, so check LastErrorCode before treating '' as an error. Extraction failures report 517 (PDFLIB_ERROR_MARKDOWN_EXPORT); bad arguments, including a page range that resolves to no pages, report 113

DOCX without Office on the machine

SaveDOCXToFile and SaveDOCXToStream write the WordprocessingML package themselves: the ZIP container, the document, numbering and relationship parts, and PNG media. Nothing calls into Word or COM, so the conversion runs on a headless server, under a service account or in a container, all places where Office automation is either unlicensed, unstable or not installed

uses
  Classes, SysUtils, PDFlibrary;

var
  Pdf: TPDFlib;
  Target: TFileStream;
  Written: Integer;
begin
  Pdf := TPDFlib.Create;
  try
    if Pdf.LoadFromFile('handbook.pdf', '') = 0 then
      raise Exception.Create('Cannot open handbook.pdf');
    Target := TFileStream.Create('handbook.docx', fmCreate);
    try
      Written := Pdf.SaveDOCXToStream('1-40',
        PDF_DOCX_INCLUDE_IMAGES or PDF_DOCX_DETECT_HEADINGS or
        PDF_DOCX_PRESERVE_STYLES or PDF_DOCX_PRESERVE_PAGE_BREAKS,
        Target);
    finally
      Target.Free;
    end;
    // Written equals the number of pages in the range on success
    if Written <> 40 then
      raise Exception.CreateFmt('DOCX export stopped after %d pages, error %d',
        [Written, Pdf.LastErrorCode]);
  finally
    Pdf.Free;
  end;
end;

Lists are written with Word's own numbering definitions rather than typed-in '1.' prefixes, so inserting an item in Word renumbers the rest. Detected tables become real Word tables with column widths taken from the measured column edges and a shaded header row. With PDF_DOCX_PRESERVE_PAGE_BREAKS set, each source page starts on a new Word page, except where a table continues from the previous page; that break is dropped so the table stays one table. Leave the flag off when users will reflow the text anyway, since a hard break every 40 lines gets in their way

The return value is the page count written. A stream export that returns fewer pages than you asked for has failed partway, and the stream holds an incomplete package, so discard it rather than handing it to Word

Deterministic DOCX packaging

Two conversions of the same PDF with the same options produce a byte-for-byte identical DOCX file, so you can hash the output to detect change, diff two builds of a generated document, and cache results without worrying that an identical input produced a different artefact

PDF Library for Delphi diagram of deterministic DOCX packaging built entry by entry in pure Pascal beside Office automation whose embedded metadata shifts every conversion
Two identical conversions hash identically for diffing and caching, a property Office automation forfeits the moment it embeds fresh timestamps

Two choices make that hold. Every ZIP entry carries the same fixed DOS date, 1 January 1980, instead of the time of the run, and the core properties part has no created or modified dates. Each entry is compressed with raw Deflate only when that actually makes it smaller, so PNG media, which is already compressed, is stored as-is. You can confirm the first point with unzip -v handbook.docx: every row shows the same date

Office automation cannot give you that. Saving through Word stamps the current time into the package metadata and the ZIP headers, so the same document converted twice differs in ways that defeat a hash. The same reasoning is behind the stable file identifiers in deterministic PDF IDs for reproducible builds: once output is reproducible, verification becomes a comparison

Which inputs convert well, and which never will

Conversion quality varies more with the input than with the converter, and it is worth telling your users so up front. Tagged PDFs and cleanly generated business documents (invoices, reports, contracts) convert well: headings land as headings, tables survive, lists renumber in Word. Two-column academic layouts come through in the right reading order when the column geometry is regular, and the diagnostics will report geometric-columns for those pages. Tables that break across pages are rejoined by inference, so spot-check them. Heavily designed marketing material, where text is placed for effect rather than in reading order, gives any converter little to recover; expect to touch up the result by hand

Scanned documents are a separate case. A page that is one large image contains no text objects, so there is nothing to export until a text layer exists, and running OCR is a prerequisite for both formats. Before committing to a large batch, sample a dozen representative files and enumerate what their pages contain, as described in text search and page element enumeration; a page with images and no text runs will tell you more in a second than reading the converted output will

Pick the format by what happens next. Markdown suits machines and pipelines: headings become chunk boundaries, tables stay readable as pipe tables, and page markers give every chunk a citation. DOCX suits people who need to change the document, because what they want back is an editable file in Word, with real lists and real tables, and the text alone does not give them that

PDF Library for Delphi ships for Delphi, C++Builder and Lazarus, with DLL and ActiveX editions that expose the same Markdown and DOCX export calls to C#, C++ and scripting hosts. The reference for every option flag and a trial download are on the PDF Library for Delphi product page