How to Convert PDF to Markdown Without Losing Formatting

Converting a PDF to Markdown sounds simple: extract the text, add a few heading symbols and save the result as an .md file.

In practice, PDF conversion is far more complicated.

A PDF is designed to preserve the visual appearance of a page. Markdown is designed to preserve the logical structure of a document. The converter therefore has to determine which text is a heading, which lines belong to the same paragraph, which values form a table and which images belong to specific captions.

A good PDF-to-Markdown conversion should produce a document that is clean, editable and structurally faithful to the original source.

This guide explains how the process works, why basic PDF extraction often fails and how to preserve headings, tables, links, images and scanned text.

What is PDF-to-Markdown conversion?

PDF-to-Markdown conversion transforms the content of a PDF into structured Markdown syntax.

A PDF section that visually contains a title, paragraph and list might become:

# Document Title

This is the introductory paragraph.

## Key findings

- First finding
- Second finding
- Third finding

The result is no longer a fixed visual page. It becomes reusable structured content that can be edited in a text editor, stored in Git, imported into Obsidian or processed by documentation and AI systems.

Why copying text from a PDF is not enough

PDF files do not always store text in the same order in which a person reads it.

A page might visually show:

The system processes the document locally
and preserves its logical structure.

Internally, the PDF may store it as separate positioned fragments:

The system processes
the document locally
and preserves its
logical structure.

A basic text extractor often treats every visual line as a separate paragraph. This produces broken sentences and unnecessary line breaks.

Other common extraction problems include:

• repeated headers inside the document;
• page numbers inserted into paragraphs;
• mixed reading order on multi-column pages;
• table values separated from their labels;
• captions detached from images;
• missing text on scanned pages;
• words split by line-end hyphenation;
• headings flattened into ordinary text.

A reliable converter must reconstruct the document rather than merely copy its characters.

The main stages of PDF-to-Markdown conversion

1. PDF loading and validation

The converter first checks whether the file can be processed.

This may include checking:

• file type;
• file size;
• page count;
• password protection;
• whether the PDF contains readable text;
• whether individual pages require OCR.

A mixed PDF may contain digital text on some pages and scanned images on others. Each page therefore needs to be classified separately.

2. Text extraction

Digital PDFs usually contain embedded text objects. These objects include information such as:

• the characters;
• font size;
• font family;
• coordinates;
• width and height;
• rotation;
• page position.

Text extraction retrieves these objects, but they still have to be grouped into words, lines and paragraphs.

3. Layout analysis

Layout analysis determines how elements on the page relate to one another.

The converter may need to identify:

• single-column text;
• multi-column text;
• sidebars;
• tables;
• captions;
• footnotes;
• forms;
• diagrams;
• page headers and footers.

A page should not automatically be classified as entirely single-column or entirely two-column. Many documents combine several layout types on the same page.

4. Reading-order reconstruction

Correct reading order is essential.

For a normal two-column report, the expected order is usually:

• complete the left column;
• continue at the top of the right column.

For a bilingual manual, the correct structure may instead pair corresponding blocks:

The converter must distinguish continuous columns from parallel content.

5. Semantic classification

Once the page structure has been identified, blocks can be classified as:

• headings;
• paragraphs;
• lists;
• numbered instructions;
• tables;
• images;
• captions;
• code;
• notes;
• references.

This classification determines the final Markdown syntax.

Preserving heading hierarchy

A useful Markdown document should normally contain one main H1 title.

Subsequent sections should use consistent H2, H3 and H4 levels.

# Maintenance Manual

## Safety Instructions

### Electrical Isolation

### Pressure Release

## Preventive Maintenance

Heading detection should consider more than font size.

Useful signals include:

• font weight;
• spacing before and after the block;
• page position;
• chapter numbering;
• alignment;
• consistency across the document;
• whether the phrase appears in a table of contents.

A large number, table label or figure caption should not automatically become a heading.

Rebuilding clean paragraphs

Visual line breaks should usually be removed when they occur inside a paragraph.

Raw extraction:

Browser-based document conversion
can preserve privacy because the file
does not need to leave the device.

Clean Markdown:

Browser-based document conversion can preserve privacy because the file does not need to leave the device.

However, the converter must not remove every line break indiscriminately.

Real boundaries must remain between:

• separate paragraphs;
• headings and body text;
• list items;
• table rows;
• addresses;
• code blocks;
• quotations.

Paragraph reconstruction therefore depends on spacing, indentation, punctuation and regional layout.

Repairing line-end hyphenation

A PDF may visually split a word across two lines:

The document trans-
formation completed successfully.

The expected result is:

The document transformation completed successfully.

But legitimate compounds must remain unchanged:

• browser-based;
• machine-readable;
• PDF-to-Markdown;
• low-confidence;
• end-to-end.

Hyphen repair should only occur when the hyphen was likely introduced by visual line wrapping.

Preserving numbered procedures

Numbered sequences are especially important in technical manuals and operating instructions.

Correct Markdown:

1. Isolate the electrical supply.
2. Verify zero pressure.
3. Remove the protective guard.
4. Inspect the mechanical seal.
5. Record the result.

The number and its associated description must remain part of the same semantic element.

A converter should also detect suspicious sequences such as:

1, 2, 3, 5

A missing number may indicate that a step was incorrectly classified or placed elsewhere in the document.

Converting PDF tables to Markdown

PDF tables are difficult because many PDFs do not contain real table cells. They contain words placed at specific coordinates.

The converter has to infer:

• table boundaries;
• column positions;
• row positions;
• header rows;
• multiline cells;
• merged cells;
• continuation lines.

A simple table can be represented as standard Markdown:

| Metric | Current | Target |
|---|---:|---:|
| Pressure | 6.8 bar | 7.0 bar |
| Temperature | 62 C | Below 75 C |
| Vibration | 3.2 mm/s | Below 4.5 mm/s |

Complex tables may require HTML, CSV or structured JSON when merged cells cannot be represented accurately in standard Markdown.

For dedicated table extraction, use Extract Tables from PDF.

Preserving links

Links in a PDF are often stored as separate annotations placed over visible text.

The visible text may say:

Technical documentation

while an invisible annotation contains the URL.

A good converter combines both elements:

[Technical documentation](https://example.com/documentation)

Without annotation processing, the words may be extracted while the destination URL is lost.

Extracting images and captions

When a PDF contains embedded raster images, those images can be extracted and referenced from Markdown:

![System overview](assets/system-overview.png)

*Figure 1. System components and sensor locations.*

An organised export might contain:

document.md
assets/
  system-overview.png
  pressure-chart.png

Not every visible graphic is an embedded image.

Some covers, diagrams and illustrations are built from:

• vector paths;
• lines;
• shapes;
• text objects;
• page backgrounds.

These may not exist as standalone PNG or JPEG files.

Use PDF to Markdown with Images when you need both the Markdown document and its extractable visual assets.

Converting scanned PDFs with OCR

A scanned PDF may contain no machine-readable text.

The page is effectively an image, even though a person can read it.

OCR conversion normally involves:

• rendering the page;
• detecting orientation;
• correcting skew;
• recognising words;
• grouping words into lines;
• rebuilding paragraphs and lists;
• assigning reading order;
• marking uncertain results.

OCR quality depends on:

• scan resolution;
• contrast;
• page rotation;
• document language;
• font quality;
• handwriting;
• shadows and stains;
• layout complexity.

Scanned and image-only documents can be processed with Scanned PDF to Markdown.

Removing repeated headers, footers and page numbers

Reports and manuals often repeat the same elements on every page:

NORTHLINE INDUSTRIES
INTERNAL USE
Page 4 of 12

These elements are useful in the PDF but distracting in Markdown.

A converter can identify recurring page-edge content by comparing:

• text;
• position;
• font;
• frequency across pages.

The output should remove repeated instances without altering the original PDF or rewriting its content.

Markdown versus visual reproduction

Markdown is not intended to reproduce a PDF pixel for pixel.

It preserves logical structure rather than exact design.

Markdown can preserve:

• headings;
• paragraphs;
• lists;
• tables;
• links;
• image references;
• code blocks;
• quotations.

It does not preserve:

• exact page positioning;
• decorative typography;
• complex background designs;
• floating visual elements;
• every vector drawing.

The goal is a reusable and editable representation of the content.

When should the converted document be reviewed?

Manual review is recommended when the PDF contains:

• merged tables;
• handwritten notes;
• equations;
• unusual fonts;
• rotated text;
• low-resolution scans;
• complex diagrams;
• irregular footnotes;
• presentation-style text boxes;
• parallel language columns.

A converter should flag uncertain regions instead of silently presenting a potentially incorrect structure.

Frequently asked questions